Overview
This provides advanced technical information related to the repo integrations.
Supported Package Manager Dependency Files
build.gradle
build.gradle.kts
cargo.toml
dependencies.scala
pom.xml
setup.py
requirements.txt
Gemfile.lock
package.json
package-lock.json
bower.json
go.mod
Gopkg.lock
Godeps.lock
vendor.conf
gogradle.lock
glide.lock
composer.json
build.sbt
packages.config
packrat.lock
paket.dependencies
Pipfile
Podfile
pyproject.toml
poetry.lock
pubspec.yaml
environment.yml
yarn.lock
Any metafile with one of the following extensions:
asp
aspx
config
csproj
do
htm
html
jsp
shtml
tf
xhtml
Technical Information for Self-Hosted Integrations
Modifying the Scanner Dockerfile
The wss-scanner image Dockerfile is located in the wss-scanner\docker\ folder.
By default, the following package managers are installed:
Maven (3.5.4)
npm
Bower
Yarn
Gradle
Pip and Pip3 (Python)
If you would like to add support for additional package managers, uncomment the relevant lines in the Dockerfile. The following package managers are available as part of the commented lines in the Dockerfile:
Mix (Elixir)
Hex (Erlang)
Go Modules, Dep, godep, VNDR, govendor, gopm, glide (Go)
Cabal (Haskell)
Paket, NuGet (.NET)
Composer (PHP)
Poetry (Python)
Packrat (R)
Bundler (Ruby)
Cargo (Rust)
SBT (Scala)
Cocoapods (Swift)
If a package manager you would like to scan is not mentioned above, please contact WhiteSource Support.
Required Open Ports
The wss-scanner Docker Container
The wss-scanner Docker container communicates with the following components using the following ports:
WhiteSource SaaS API → Port 443
Your repository platform’s git protocol → The default is port 9418
Private/public package registries (npmjs/pypi/ruby gems, etc.) which use the standard ports
The wss-gls-app/wss-ghe-app/wss-bb-app Docker Container
The wss-app Docker container communicates with the following components using the following ports:
Your repository platform instance API → Check the port number with your repository platform Admin.
The WhiteSource SaaS API → Port 443
The wss-remediate server Docker container port as configured by the user → The default is 8080.
The wss-remediate Docker Container
The wss-remediate Docker container communicates with the following components using the following ports:
Inbound:
Requests are received via a single port (default is 8080) from the wss-app Docker container
Outbound:
Internally:
Your repository platform instance over https (default port is 443)
Externally:
WhiteSource SaaS API → Port 443.
Private/public package registries (npmjs/pypi/ruby gems, etc.) which use the standard ports
Repository Platform
Your repository platform instance requires the ability to communicate with the following components using the following ports:
wss-<integration_type>-app Docker container → Recommended is 5678
wss-remediate Docker container → Recommended is 8080
wss-scanner Docker container → Recommended is 9393
NOTE: All port numbers on the Docker containers are the user’s choice
Enabling HTTPS Support for the Webhook Interceptor
The app container supports two ways of enabling HTTPS protocol for the webhook interceptor:
Using Java KeyStore containing valid certificate and private key, as environment variables:
WS_KEYSTORE_FILE_PATH - path to the keystore file
WS_KEYSTORE_PASSWORD - password for the keystore file
Directly provide a certificate and private key files, as environment variables:
WS_HTTPS_CERT_FILE_PATH - path to the certificate file
WS_HTTPS_KEY_FILE_PATH - path to the private key file
App Container Startup Check
Available from version 21.1.2 of the integration
Upon startup, the app container provides a clear indication of the connectivity status between itself and the remediate container, the repository platform (SCM) API, and the WhiteSource application server. The startup check also validates the activation key provided in the initial configuration. If needed, error messages are displayed. Each check results in one of three status types, as listed here:
SUCCESS
FAILED
SKIPPED
Check Name | Check Description | Notes |
---|---|---|
Activation Key Parsing | Verifies the activation key is valid. | If this check returns FAILED, the controller will shut down. |
WhiteSource API Connectivity | Checks the connectivity with the WhiteSource application server. | If this check returns FAILED, the controller will shut down. |
Activation Key Validation | Validates the content of the parsed activation key. | If this check returns FAILED, the controller will shut down. |
WhiteSource Credentials | Checks that the WhiteSource service user (generated as part of the integration) has regular and admin access to the integrated WhiteSource organization. | |
Queue Implementation | Checks the WhiteSource application server queue implementation (ability to send and receive messages). | |
SCM API Connectivity | Checks the connectivity with the SCM (Bitbucket, GitHub, or GitLab) API. | |
Controller to Remediate Connectivity | Checks the connectivity from the wss-app container to the Remediate container. | |
Remediate to Controller Connectivity | Checks the connectivity from the Remediate container to the wss-app container. | |
GitHub App Permissions | Checks that the GitHub App has all the required minimal permissions and event subscriptions in place. | Only relevant for WhiteSource for GitHub Enterprise. |
When all checks are finished, a summary table will be written to the log, for example:
Environmental Variables
NOTE: The old names are still supported for backward compatibility. If they exist, the environment variables will take precedence over properties in the prop.json file.
Environment Variables | Description | Controller | Scanner | Remediate | prop.json property | Notes | Supported from version |
---|---|---|---|---|---|---|---|
WS_ACTIVATION_KEY | Your generated activation key in the WhiteSource application | V | V | V | bolt.op.activation.key | The property should still exist in the prop.json file, its value is disregarded. | 21.7.2 |
WS_CONFIG_ACCOUNT_NAME | The account name that will hold the global whitesouce-config repository. Default: “whitesource-config” | V | X | X | X | 21.6.3 | |
WS_CONFIG_REPO_NAME | The repository name of the global configuration repository. Default: “whitesource-config” | V | X | X | X | 21.6.3 | |
WS_HTTPS_CERT_FILE_PATH | If using a certificate file - path to the certificate file | V | X | X | X | 21.6.3 | |
WS_HTTPS_KEY_FILE_PATH | If using a certificate file - path to the private key file | V | X | X | X | 21.6.3 | |
WS_KEYSTORE_FILE_PATH | If using a Java keystore - path to the keystore file. | V | X | X | X | 21.6.3 | |
WS_KEYSTORE_PASSWORD | If using a Java keystore - password for the keystore file | V | X | X | X | 21.6.3 | |
WS_CREATE_ISSUES | The ability to globally enable/disable Issues creation across all of your organization's repositories. Default: true | V | X | V | bolt4scm.create.issues | 21.7.1 | |
WS_CREATE_CHECK_RUNS | The ability to globally enable/disable build statuses across all of your organization's repositories. Default: true | V | X | X | bolt4scm.create.check.runs | It is strongly recommended not to set this value to false, since the diff functionality relies on the check run, and this is one of the important means to update on the status of a scan. With this feature disabled there is no way of knowing what's going on if a scan failed, succeeded, found vulnerabilities, etc. | 21.6.3 |
WS_REMEDIATE_WEBHOOK_URL | The destination of the Remediate network endpoint to intercept webhooks. Default: http://remediate-server:8080/webhook | V | X | X | webhook.remediate.url | Must include the “/webhook” suffix | 21.6.3 |
WS_UA_LOG_IN_CONSOLE | If set to true the UA logs will also be printed to the stdout, like the scanner logs. | X | V | X | X | The UA logs can be very long. | 21.7.2 |
WS_LOG_DIRECTORY | Configure the path to both the scanner and the UA log files. Using this property will also append a partial request token to the log filenames. | X | V | X | X | 21.7.2 | |
WS_REMEDIATE_SERVER_ONLY | Indicates whether a Remediate container is marked as server. The Remediate server enques jobs for the Remediate workers. | X | X | V | X | There can be only 1 Remediate server | 21.7.1 |
WS_REMEDIATE_SERVER_URL | The url of the Remediate server. This indicates that the Remediate container is a worker and pulls jobs from the Remediate server. | X | X | V | X | Ignored if WS_REMEDIATE_SERVER_ONLY is specified. | 21.7.1 |
WS_PROP_JSON_FILE_PATH | Path to the prop.json file. | X | X | V | X | 21.7.1 | |
WS_CONTROLLER_DESTINATION_URL | The url of the Controller network endpoint. | X | X | V | V | 21.7.1 | |
WS_HOST_RULES_PRIVATE_KEY | The PGP private key generated for the Private Registry support. | V | V | V | X | Cannot be used at the same time with WS_HOST_RULES_PRIVATE_KEY_FILE_PATH | 21.9.1 |
WS_HOST_RULES_PRIVATE_KEY_FILE_PATH | The PGP private key generated for the Private Registry support. | V | V | V | X | This file should be mapped to the running containers. | 21.9.1 |
WS_GIT_CONNECTOR | Enable cloning project files through Git shell commands. To enable, set value to true Default: false | X | V | X | X | By default, the Scanner uses JGit library for any Git-related operations. | 21.9.1 |
LOG_FORMAT | If set to | X | X | V | X | ||
WS_CACHE_TYPE | Defines one of three available caching mechanisms:
| V | X | X | X | 22.2.1 | |
WS_REDIS_HOST | The host address (e.g., “localhost”). Mandatory if WS_CACHE_TYPE=REDIS | V | X | X | X | 22.2.1 | |
WS_REDIS_PORT | (Optional) The Redis port on the host. Default: 6379. | V | X | X | X | 22.2.1 | |
WS_REDIS_PASSWORD | Password to the Redis cluster. Default: null. | V | X | X | X | 22.2.1 | |
WS_REDIS_SSL_ENABLED | Set to true if the Redis Cluster works with the SSL protocol. Default: false. | V | X | X | X | 22.2.1 |