...
Configuration File Parameter | Description and Expected Behavior | If True | If False | Default | Command Line Parameter Available? | ||||||
---|---|---|---|---|---|---|---|---|---|---|---|
checkPolicies | Whether to send the check policies request before updating WhiteSource.
| In case of policy violation, the scan will end with ERROR exit code POLICY_VIOLATION (-2). | The scan will end with SUCCESS. Inventory will be updated regardless of policy violations. | False | No | ||||||
forceCheckAllDependencies | Force checks all dependencies. NOTE: Used only if if checkPolicies is and updateInventory is set to True. | Checks all policies for all dependencies introduced to the WhiteSource projects. | Checks only the new dependencies introduced to the WhiteSource projects. | False | No | ||||||
updateInventory | Whether to send an update request. | Sends an update request. | Sends a check policies request to WhiteSource without sending the update request; meaning the user will perform checkpolicies request without updating its inventory in WhiteSource. | True | No | ||||||
forceUpdate | Whether to update organization inventory regardless of policy violations. NOTE: Used only if checkPolicies is set to True. | Updates the project even if the checkPolicies step failed.
| In case of a policy violation:
| False | No | ||||||
forceUpdate.failBuildOnPolicyViolation | Determines whether the Unified Agent exit code will be the result of the policy check or the result of the scan. NOTE: Used only if forceUpdate is set to True. | The Unified Agent exit code will be the result of the policy check, meaning if there is a failure in checkpolicies the exit code is -2. | The Unified Agent exit code will be the result of the scan. (success or failure) | False | No | updateInventory | Whether to send an update request. | Sends an update request. | Sends a check policies request to WhiteSource without sending the update request; meaning the user will perform checkpolicies request without updating its inventory in WhiteSource. | True | No |
General
Miscellaneous parameter settings.
...
Configuration File Parameter | Description and Expected Behavior | If True | If False | Default | Command Line Parameter Available? |
---|---|---|---|---|---|
offline | Whether to create an offline update request instead of sending one to WhiteSource. | An offline request file is created in the whitesource folder next to the scanned project. | Results are sent directly to the server. | False | -offline |
updateType | If scanning a previously-scanned project, whether to append or override the results.
| N/A | N/A | OVERRIDE | -updateType |
ignoreSourceFiles | Whether to only include package dependencies for all package managers/dependency resolvers. IMPORTANT: As of version 21.2.2, this parameter is being deprecated and will be replaced by a new parameter, fileSystemScan. | Overrides the individual NOTE: When ignoreSourceFiles is used, then the includes/excludes parameter will be ignored. | No override action will occur, and each of the package manager's | False | No |
fileSystemScan | Performs a file system scan for source files and binaries, in addition to the package manager based dependencies resolution. The files to be scanned can be controlled by the includes and excludes parameters and the resolver-specific ignoreSourceFiles parameters. IMPORTANT: This parameter is new for version 21.2.2, and overrides the soon-to-be-deprecated ignoreSourceFiles. | Performs a file system scan for source files and binaries, in addition to the package manager based dependencies resolution. | Only package manager based dependencies resolution is being performed. | True | No |
scanComment | Adds a comment to a scan. The comment is then displayed in the Project Vitals panel of the Project pages, and the Plugin Request History Report. Supports UTF-8 characters. | A comment is added to the scan. | No comments will be added to the scan. | No default | -scanComment |
faileErrorLevel failErrorLevel | When set to ALL - the Unified Agent will exit on any major error (such as resolution failed, pre-steps error, etc.) Otherwise, there is no change in behavior. Possible values - ALL or DEFAULT (upper-case only) | N/A | N/A | "DEFAULT" | No |
requireKnownSha1 | Checks for dependencies with known/unknown SHA-1. | The Unified Agent will terminate the scan if one or more dependencies with an unknown SHA-1 were found. | The scan will continue normally. | True | -requireKnownSha1 |
generateProjectDetailsJson | Whether to generate a JSON file upon scan completion containing the projectTokens and projectNames. | The Unified Agent generates a JSON file at the end of the scan named scanProjectDetails.json containing the projectTokens and projectNames. | The JSON file report will not be generated. | False | No |
generateScanReport | (For Organization and Product Administrators only) Whether to create a report in JSON format at the end of the scan, which includes information on vulnerabilities, policy violations, top fixes, and inventory details. The filename format is '<project_name>-<yyyy-mm-dd>T<HHmmss>+<UTC offset>-scan_report.json'. NOTES:
| A report in JSON format is created at the end of the scan, which includes information on vulnerabilities, policy violations, top fixes, and inventory details. | The report will not be generated. | False | -generateScanReport |
scanReportTimeoutMinutes | Time-out (in minutes) for the process of generating the scan report. If the timeout interval has passed then the report will not be generated, but the scan will continue. | N/A | N/A | 10 | No |
scanReportFilenameFormat | Controls the filename format of a generated scan report.
| N/A | N/A | Default value is " | No |
updateEmptyProject | Whether to create an empty project in WhiteSource or to update an existing project with empty data. NOTE: This parameter affects all resolvers/package managers. | Updates/creates a project even if there are no dependencies. | Will not create/ update the empty project. | True | No |
log.files.level | For storing logs by default, this determines the log's level:
NOTES:
wss-scan-<date>-<time> | N/A | N/A | Debug | -log.files.level |
log.files.maxFileSize | For storing logs by default, this is the maximum size in MB. If exceeding this size, the file will be overridden. NOTE: This reflects one run (cycle) of the Unified Agent. The files accumulate after each run. | N/A | N/A | 10 MB | No |
log.files.maxFilesCount | For storing logs by default, this is the maximal count of log files. If exceeding this size, the oldest files will be overridden with new files. NOTE: This reflects one run (cycle) of the Unified Agent. The files accumulate after each run. | N/A | N/A | 3 | No |
log.files.path | Location of the created log file. NOTE: In Windows, do not put " | N/A | N/A | The default location of the logs is in the 'whitesource' folder (determined by the whiteSourceFolderPath parameter) | No |
sendLogsToWss | Whether to send logs to WhiteSource. | Sends logs to WhiteSource. | Will not send logs to WhiteSource. | False | No |
case.sensitive.glob | Whether the file system should be case sensitive. | The file system will be case sensitive. | The file system will not be case sensitive. | False | No |
showProgressBar | Whether to display a progress bar inside logs. NOTE: This parameter is valid for the Unified Agent only (not Prioritize). | Progress bars will be displayed inside logs. | Progress bars will not be displayed inside logs. | True | No |
...
Configuration File Parameter | Description and Expected Behavior | If True | If False | Default | Command Line Parameter Available? |
---|---|---|---|---|---|
python.resolveDependencies | Whether to resolve python dependencies. "requirements.txt" or "pipfile" are required. | Resolves python dependencies | Will not resolve python dependencies. | True | No |
python.ignoreSourceFiles | When using the dependency resolver, it will only include package dependencies, not source files. NOTE: Only relevant when fileSystemScan is true. | Ignores *.py files in scan. | Will not ignore files which have ".py" extension. | True | No |
python.ignorePipInstallErrors | Whether to ignore errors of 'pip download -r requirements.txt' command. | Ignores download errors, and try to download packages one by one | Will consider such errors and react accordingly | False | No |
python.installVirtualenv | Whether to install the pip 'virtualenv' package on --user. | Installs a virtual environment the virtualenv package by running "python -m pip install --user virtualenv" | Will not run install the command virtualenv package | False | No |
python.resolveHierarchyTree | Whether to resolve the hierarchy tree or a flat list of dependencies, requires "requirements.txt" like files. | Will install pipdeptree and use it to resolve and find the dependency hierarchy tree | Will resolve a flat list only | True | No |
python.requirementsFileIncludes | Space-delimited list of dependency filenames specifying which files to be scanned for dependencies, instead of "requirements.txt", when using pip package manager. | N/A | N/A | requirements.txt | No |
python.resolveSetupPyFiles | Whether to resolve python dependencies in setup.py files, and if so, it executes the setup.py script in order to install and resolve dependencies. | Executes setup.py in order to install and resolve dependencies | Will ignore setup.py files | False | No |
python.runPipenvPreStep | Whether to run pipenv install command. If so, it requires "pipfile". | Runs the 'pipenv install' command. | Will not run the command | False | No |
python.pipenvDevDependencies | Whether or not to install "dev" dependencies, if so it requires "python.runPipenvPreStep=true" | Adds --dev to the command, resulting in: "pipenv install --dev" | Will not adds --dev to the command | False | No |
python.IgnorePipenvInstallErrors | Whether to ignore errors of the 'pipenv run pip download' command. | Ignores download errors, and try to download packages one by one | Will consider such errors and react accordingly | False | No |
python.resolveGlobalPackages | Whether to resolve global packages or not. If so, it requires global package folders called site-packages or dist-packages in your scan directory. | If set to True and there is a site-packages or dist-packages folder, the resolution will be based on the packages under those folders. | Will not resolve global packages | False | No |
python.resolvePipEditablePackages | The parameter handles requirements.txt files with rows (packages) with the -e flag. | Resolves the dev dependencies on the first scan. | Will not resolve the dev dependencies on the first scan. | False | No |
python.path | Points to the python executable path. If the executable path is already set in the environment variables, then just the executable name can be defined, e.g. in Linux "python2.7". NOTE: This parameter replaces "python" executable with the value defined. | N/A | N/A | python | No |
python.pipPath | Enables you to use different versions of pip. If set to pip3, will run "pip3" and "python -m pip3" instead of "pip" and "python -m pip". | N/A | N/A | pip | No |
python.runPoetryPreStep | Whether to run "poetry install" command. | Will run the "poetry install" command | Will not run the "poetry install" command | False | No |
python.includePoetryDevDependencies | Whether to scan Poetry project dev dependencies. | Scans Poetry project dev dependencies | Will ignore dev dependencies | False | No |
python.localPackagePathsToInstall | A space-delimited list of local package paths that will be installed during the pre-step, if is required. | N/A | N/A | Empty | No |
python.indexUrl | The local Pypi repository url, besides the official Pypi repository. Use if you have dependencies downloaded from a different source than the default pypi. | N/A | N/A | No | |
python.includePipenvDevDependencies | Enables you to include or exclude dev dependencies. | Include dev dependencies in the resolution. | Exclude dev dependencies in the resolution. | True | No |
...
Configuration File Parameter | Description and Expected Behavior | If True | If False | Default | Command Line Parameter Available? |
---|---|---|---|---|---|
haskell.resolveDependencies | Whether to resolve Haskell dependencies using the Cabal package manager. | Resolves Haskell Cabal projects | Will not resolve Haskell Cabal projects | True | No |
haskell.runPreStep | Runs the 'cabal sandbox init' and 'cabal install' commands on each package/project found. for cabal version 3.* the UA will use the command "cabal new-build" and resolve the file plan.json | Runs 'cabal install' If sandbox is missing it will run 'cabal sandbox init' (before cabal install) | The Unified Agent assumes that a sandbox already exists in each package, and will fail otherwise. | False | No |
haskell.ignoreSourceFiles | When using the dependency resolver, it will only include package dependencies, not source files. NOTE: Only relevant when fileSystemScan is true. | Ignores .hs and .lhs files from scan. | Will not ignore .hs and .lhs files from the scan. | True | No |
haskell.ignorePreStepErrors | Ignores errors from preStep commands and continues trying to resolve dependencies. | Behaves according to 'failErrorLevel' flag | Will continue the scan, ignoring any errors in the pre-step process. | False | No |
...
OCaml
Configuration File Parameter | Description and Expected Behavior | If True | If False | Default | Command Line Parameter Available? |
---|---|---|---|---|---|
ocaml.resolveDependencies | Whether to resolve dependencies. | Resolves Ocaml projects. | Will not resolve Ocaml projects. | False | No |
ocaml.runPreStep | Whether to install required dependencies. | Installs required dependencies. | Will not install required dependencies. | False | No |
ocaml.ignoreSourceFiles | When using the dependency resolver, it will only include package dependencies, not source files. NOTE: Only relevant when fileSystemScan is true. | Includes package dependencies, not source files. | Will include package dependencies and source files. | True | No |
ocaml.switchName | switch name used for install current project dependencies | N/A | N/A | The default uses activated switch | No |
ocaml.ignoredScopes | Define which exact scope names to ignore. Available values are
| N/A | N/A | No, default is "with-test with-doc" | No |
ocaml.aggregateModules | Whether to aggregate all opam packages/modules. | Aggregates all opam packages/modules. | Will not aggregate opam packages/modules. | False | No |
...
includes=**/*.c **/*.cc **/*.cp **/*.cpp **/*.cxx **/*.c++ **/*.h **/*.hpp **/*.hxx
#includes=**/*.m **/*.mm **/*.js **/*.php
#includes=**/*.jar
#includes=**/*.gem **/*.rb
#includes=**/*.dll **/*.cs **/*.nupkg
#includes=**/*.tgz **/*.deb **/*.gzip **/*.rpm **/*.tar.bz2
#includes=**/*.zip **/*.tar.gz **/*.egg **/*.whl **/*.py
...
Configuration File Parameter | Description and Expected Behavior | If True | If False | Default | Command Line Parameter Available? | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
docker.scanImages | Runs scans on all or specified images. See here for more information on scanning Docker images. | Only the Docker image scan will occur. | Docker image scan will not take place. | False | -docker.scanImages | |||||||||
docker.includes | Comma, space or line-delimited list specifying which images to include in the scan. Values provided should come from either of the following:
| N/A | N/A | The default value is ".*.*" (All images will be scanned) | No | |||||||||
docker.excludes | Comma, space or line-delimited list specifying which images to exclude in the scan. Values provided should come from either of the following:
| N/A | N/A | The default value is "" (No images will be excluded) | No | |||||||||
docker.pull.enable | Whether to execute "pull" from all from all relevant registries | Executes 'pull' from all relevant registries | Will not pull anything | False | No | |||||||||
docker.pull.images | Pull Docker images that match the specified filter (string). Can include regular expressions or a list of space-delimited values. | N/A | N/A | The default value is "" (all images will be pulled) | No | |||||||||
docker.pull.maxImages | Defines the maximum number of images to be pulled. When this number of pulled images is reached, no more images are pulled. | N/A | N/A | 10 | No | |||||||||
docker.pull.tags | Pulls Docker images whose tags match the specified filter (string). Can include regular expressions or a list of space-delimited values. | N/A | N/A | The default value is "" (all images will be pulled) | No | |||||||||
docker.pull.digest | Pull Docker images whose digests match the specified filter (string). Can include regular expressions or a list of space-delimited values. | N/A | N/A | The default value is "" (all images will be pulled) | No | |||||||||
docker.delete.force | Enables WhiteSource to use Docker to delete images via the 'force' flag. This is required if the user pulled images that are related to other images, so in this case a regular delete may not work. NOTE: Use this parameter with caution. | WhiteSource uses Docker to delete images via the 'force' flag. | WhiteSource will not use Docker to delete images via the 'force' flag. | False | No | |||||||||
docker.login.sudo | Whether the Unified Agent will run 'sudo docker login'. | The Unified Agent will run 'sudo docker login'. | The Unified Agent will not run 'sudo docker login'. | True | No | |||||||||
docker.projectNameFormat | Determine's the Docker project's name's format.
N/NOTE: Irrelevant when docker.scanTarFiles=true. | N/A | N/A | "DEFAULT" | No | |||||||||
docker.scanTarFiles | Used when the user supplies the tar file of a Docker image. NOTE: The project name will be derived from the tar file name. | The Unified Agent will scan the .tar file as a Docker image. | The Unified Agent will not scan the .tar file as a Docker image. | False | No | |||||||||
docker.layers | Enables users scanning docker images to receive information regarding packages in layer granularity. The layer granularity can be viewed in the interface under the hierarchical display. | Provides information packages in layer granularity. The scan will split the result into layers, each layer contains all packages/libraries and files found under the layer (in case a package was added at layer 2 and deleted from 3, it will not appear at all in the result, since its not part of the final result). | Will not provide the aforementioned information. | False | No | |||||||||
docker.aws.enable | Enables pulling Docker Images from Amazon Elastic Container Registry (ECR). NOTE: If set to True, the 'docker.scanImages' and 'docker.pull.enable' parameter values are also set to True. | Pulls Docker Images from Amazon Elastic Container Registry (ECR). | Will not pull Docker Images from Amazon Elastic Container Registry (ECR). | False | No | |||||||||
docker.aws.registryIds | The Registry IDs list on Amazon Web Services (the AWS 12-digit account IDs that correspond to the Amazon ECR registries). The list must include the following:
NOTE: Required if docker.aws.enable=true. | N/A | N/A | No default | No | |||||||||
docker.azure.enable | Enables pulling Docker Images from Azure Container registry. NOTE: If set to True, the 'docker.scanImages' and 'docker.pull.enable' parameter values must also be set to True. | Pulls Docker Images from Azure Container registry. | Will not pull Docker Images from Azure Container registry. | False | No | |||||||||
docker.azure.userName | Username for Azure Container registry. NOTE: Required if docker.azure.enable is True. | N/A | N/A | No default | No | |||||||||
docker.azure.userPassword | Password for Azure Container registry. NOTE: Required if if docker.azure.enable=true. However, it is not mandatory if you already logged in manually to your Azure account via the Azure Client CLI. | N/A | N/A | No default | No | |||||||||
docker.azure.registryNames | Docker registry names in Azure Container registry, space-delimited. NOTE: Required if docker.azure.enable=true. | N/A | N/A | No default | No | |||||||||
docker.azure.authenticationType | Whether to use “containerRegistry” or "userAccount" as the authentication type. Using "userAccount" login method requiere setting should be filled "docker.azure.userName" and "docker.azure.userPassword" Using "containerRegistry", login method will login to each registry using registry username and password provided in config file in the param docker.azure.registryAuthenticationParameters | N/A | N/A | userAccount | No | |||||||||
docker.azure.registryAuthenticationParameters | Registry authentication parameters should contain username and password for each registry in the following format <registryUsername>:<registryPassword>. If there are more than one registry contain in docker.azure.registryNames param then username and password should be provided separated by space: <registry1UserName>:<registry1Password> <registry2UserName>:<registry2Password> | N/A | N/A | No default | No | |||||||||
docker.artifactory.enable | Enables pulling Docker Images from the Artifactory Pro Docker registry. NOTE: Verify that the 'docker.scanImages' and 'docker.pull.enable' parameter values are also set to True. | Pulls Docker Images from the Artifactory Pro Docker registry. | Will not pull Docker Images from the Artifactory Pro Docker registry. | False | No | |||||||||
docker.artifactory.url | Artifactory URL including http:// or https:// and contextpath (Artifactory default contextPath is “/artifactory" ) NOTE:
| N/A | N/A | No default | No | |||||||||
docker.artifactory.pullUrl |
| N/A | N/A | No default | No | |||||||||
docker.artifactory.userName | Username for Artifactory Pro Docker registry NOTE: Required if docker.artifactory.enable=true. | N/A | N/A | No default | No | |||||||||
docker.artifactory.userPassword | Password for Artifactory Pro Docker registry. NOTE: Required if docker.artifactory.enable=true. | N/A | N/A | No default | No | |||||||||
docker.artifactory.repositoriesNames | Repository names in Artifactory Pro Docker registry, space-delimited list. NOTE: Required if docker.artifactory.enable=true. | N/A | N/A | No default | No | |||||||||
docker.artifactory.dockerAccessMethod | Required when the user has read-only access. Values are: repopath, subdomain, port. In case customers use port method 'docker.artifactory.dockerAccessMethod=port', 'repository port' must be added to each repository in ‘docker.artifactory.repositoriesNames' in this format: <repositoryName>:<repositoryPort> | N/A | N/A | No default | No | |||||||||
docker.hub.enabled | Enables pulling Docker Images from the Docker Hub registry. NOTE: Verify that the 'docker.scanImages' and 'docker.pull.enable' parameter values are also set to True. | Pulls Docker Images from the Docker Hub registry. | Will not pull Docker Images from the Docker Hub registry. | False | No | |||||||||
docker.hub.userName | Username for Docker Hub registry. NOTE: Required if docker.hub.enable=true | N/A | N/A | No default | No | |||||||||
docker.hub.userPassword | Password required for Password for Azure Container registry. NOTE: Required if docker.hub.enable=true | N/A | N/A | No default | No | |||||||||
docker.hub.organizationsNames | Space-delimited list of organizations under the user to be scanned. NOTE: Required if docker.hub.enable=true. | N/A | N/A | No default | No | docker.scanTarFiles | Used when the user supplies the tar file of a Docker image. | The Unified Agent will scan the .tar file as a Docker image. | The Unified Agent will not scan the .tar file as a Docker image. | False.enable=true. | N/A | N/A | No default | No |
docker.gcr.repositories | A list of repositories, comma-delimited. Example value: | N/A | N/A | Empty | No | |||||||||
docker.gcr.enable | Enables pulling Docker Images from Google Container Registry with Docker. NOTE: Verify that the docker.scanImages and docker.pull.enable parameter values are also set to 'true' | Pulls Docker Images from Google Container Registry with Docker. | Will not pull Docker Images from Google Container Registry with Docker. | False | No | |||||||||
docker.gcr.account | Email of Google Container Registry account. | N/A | N/A | Empty | No | docker.layers | Enables users scanning docker images to receive information regarding packages in layer granularity. The layer granularity can be viewed in the interface under the hierarchical display. | Provides information packages in layer granularity. The scan will split the result into layers, each layer contains all packages/libraries and files found under the layer (in case a package was added at layer 2 and deleted from 3, it will not appear at all in the result, since its not part of the final result). | Will not provide the aforementioned information. | False | No |
Docker Containers
...