For a complete list of supported file extensions (binary files, source files, and archive files) that the Unified Agent supports, refer here.
WhiteSource recommends using the Unified Agent. |
Language | Plugin |
---|---|
Java | Unified Agent, Maven, Jenkins, TeamCity |
.Net | Unified Agent, TFS/VSTS, Jenkins, TeamCity |
Scala | Unified Agent, Maven , Jenkins, TeamCity |
Clojure | Unified Agent, Maven , Jenkins, TeamCity |
C# | Unified Agent, TFS/VSTS, Jenkins, TeamCity |
Ruby | Unified Agent |
Python | Unified Agent |
NPM | Unified Agent, NPM |
NuGet | Unified Agent |
Bower | Unified Agent, NPM |
C/C++ | Unified Agent |
Obj-C | Unified Agent |
JavaScript | Unified Agent, Jenkins |
PHP | Unified Agent |
Go | Unified Agent |
RPM/YUM | Unified Agent |
Debian | Unified Agent |
Swift | Unified Agent |
Alpine Linux | Unified Agent |
Groovy | Unified Agent |
ActionScript | Unified Agent |
Arch Linux | Unified Agent |
If you have Java/Ruby/Python archive files and you are willing to open them and extract descriptive information, then you can use this feature by providing values for the following parameters:
The drill-down hierarchy is limited to a maximum of 10 and can be modified in the configuration file.
By default, the drill-down hierarchy level is zero - no drill down.
Supported archive types are as follows:
NOTES:
If a scanned project uses a configuration file that contains only a defined 'projectName' (where 'projectToken’, ‘productName’ and ‘productToken’ are left empty), then the Unified Agent adds the results to the first project it finds in the organization that contains the same project name.
If a multi-module project is scanned with the same configuration as described above, and a project with one of the module names already exists, then the Unified Agent adds the module data to this existing project.
projectName=NewProject projectToken= productName= productToken= |
In order to avoid overriding an existing project with the same name, from the Advanced Settings section of the Integrate page, select the checkbox Add project to default product when only project name is provided.
When this checkbox is selected, the following rules apply to all future scans:
The detection mode (Configuration Recommendation) identifies the environment that the user wants to scan and creates the configuration file automatically.
The recommendation mode is supported from Unified Agent version 19.7.2 onwards. |
This mode quickly determines the required folder's environment, such as file extensions and package managers. The output of this mode is a configuration file, which will be automatically created in the folder where the command ran: wss-generated-file.config.
The generated configuration will contain the list of recommended parameters based on the environment, and also the mandatory parameters: APIKey, ProductName, ProjectName/ProjectToken and Wss.URL.
To use the Configuration Recommendation mode, do as follows:
The includes parameter is supported by this feature, enabling WhiteSource to automatically identify the environment that the user wants to scan and create the configuration file automatically.
The following table lists the exit codes that are returned when the Unified Agent completes the scan.
These exit codes are also available after the process ends, in the environment's last command's return value variable
(Linux: $?, PowerShell: $LASTEXITCODE, Batch: %ERRORLEVEL%)
Exit Code | Exit Message | Description |
---|---|---|
0 | SUCCESS | Scan completed successfully. |
-1 | ERROR | General error has occurred. |
-2 | POLICY_VIOLATION | One or more of the scanned components violates an Organization or Product level policy. Policy summary reports are created and saved in the newly-created whitesource directory, located under the current working directory ($pwd or %cd%). Only applicable when configured to checkPolicies=true and forceUpdate=false. |
-3 | CLIENT_FAILURE | Client-side error has occurred. |
-4 | CONNECTION_FAILURE | The agent was unable to establish a connection to the WhiteSource application server (e.g., due to a blocked Internet connection). |
-5 | SERVER_FAILURE | Server-side error has occurred (e.g., a malformed request or a request that cannot be parsed was received). |
-6 | PRE_STEP_FAILURE | One of the package manager's prerequisite steps (e.g., npm install, bower install, etc.) failed. Only applicable if the appropriate property is set to true (npm.runPreStep, bower.runPreStep, etc.). |
-100 | EUA NOTICE | Analysis will commonly display the following EUA code at successful completion: [EUA000] Analysis completed successfully. The Unified Agent returns a [-100] exit code if the analysis reported an exit code other than [EUA000]. |
Exit Codes in Bash
The exit codes WhiteSource returns in the Bash command language should be treated as 'x' modulo 256:
For customers using a proxy, the relevant proxy details are defined here.
Use the CLI parameter ‘-proxy’ to allow for an easy method to set proxy settings. The following command allows you to download a remote configuration file using proxy settings:
java -jar /path/to/jar/wss-unified-agent-<x.x.x.>.jar -c "path/to/config/file/in/remote" -proxy protocol://<user>:<password>@host\:port/ |
java -jar /path/to/jar/wss-unified-agent-<x.x.x.>.jar -c "https://raw.githubusercontent.com/whitesource/unified-agent-distribution/master/standAlone/wss-unified-agent.config" -proxy http://hm:hm@192.168.1.233:808/ |
NOTE: The following protocols are supported: 'file://', 'ftp://', 'http://', 'https://'
It's possible to save the output of the scan into a file instead of sending it directly to WhiteSource by HTTPS. This approach is useful in case there is no connectivity (or limited connectivity) while scanning.
By changing the configuration file to offline mode, any execution of the Unified Agent will store the current configuration and metadata in a JSON txt file named update-request.txt, located in the newly-created 'whitesource' directory. It is located under the current working directory ($pwd or %cd%). This file can later be manually uploaded to WhiteSource from the Admin Console or via the command line.
Update the wss-unified-agent.config file:
Upload via command line with configuration file (supported from version 1.8.9):
Before you begin this procedure, ensure these parameters are properly configured:
Execute the Unified Agent with the -requestFiles flag specifying the path to the update-request.txt file you created in the previous step. In order to send more than one file, separate file names with a comma.
java -jar <path to wss-unified-agent-*.jar> -c <path of config file> -requestFiles <file-path1>[,<file-path2>] |
Upload via command line without configuration file (supported from version 1.8.9):
Execute the Unified Agent with the -requestFiles flag specifying the path to the update-request.txt file you created in the previous step. In order to send more than one file, separate file names with a comma.
java -jar <path to wss-unified-agent-*.jar> -wss.url <WhiteSourceInstance/agent> -apiKey <apiKey> -productToken <productToken> -project <newProjectName> -requestFiles <pathToUpdate-request.txt> -noConfig true |
This procedure enables you to verify the integrity of the downloaded Unified Agent's .jar file, and ensure that it originated from WhiteSource.
It is recommended to perform this procedure per release. Do as follows:
jarsigner -verify -verbose <UA jar> |
After running, ensure that the WhiteSource information appears in the list of security certificates.
For customers using SCM (Git, SVN, Mercurial), refer here for the relevant settings.
If the source code is not located on your machine, it is possible to provide connection information to your remote repository using Git, SVN or Mercurial. Note the following:
The scm client must be installed on your machine in order to successfully connect to your repository:
WhiteSource also supports on-premises installations of repositories.
NOTE: If local files are to be scanned, then remove or comment out the scm parameters.
Multiple remote repositories can be scanned by creating a JSON file, similar to the following example:
{ "scmRepositories" :[ { "url" : "path/to/remotreRepository1" , "branch" : "ChooseBranch" , "tag" : "ChooseTag" }, { "url" : "path/to/remotreRepository2" , "branch" : "master" , "tag" : "0.2" } ] } |
Remote Repository (SSH)
SSH is currently supported only for Git repositories.
Set the scm.ppk property to your private key file path and set the scm.pass property to the passphrase of the private key. If there are none, then leave empty.
If you have a proxy for your remote repositories, add these java parameters:
-Dhttps.proxyHost=PROXY_HOST -Dhttps.proxyPort=PROXY_PROT |
When the 'failErrorLevel' parameter is set to 'DEFAULT', the behavior of the exit codes stay the same.
When the 'failErrorLevel' parameter is set to 'ALL', the Unified Agent returns an error code for all errors in the scan, rather than 'SUCCESS'. This can be useful for customers migrating from the plugins (NPM, MAVEN etc.) to the Unified Agent.
The parameter sets additional scenarios to 'error' instead of 'success'.The following cases are considered as 'Failure':
Examples:
When the ignore resolver errors parameters are set to true (e.g., ‘npm.ignoreNpmLsErrors’ is set to true) the scan will not fail. If all of these parameters are set to false, then they will fail the scan. In case there are multiple revolvers and at least one failed, then all resolvers are considered as a failure. |
A summary report in JSON format can be automatically generated locally at the end of each scan, using the 'generateScanReport' configuration parameter when running the Unified Agent.
This report includes information on vulnerabilities, policy violations, top fixes and inventory details.
The default filename format of the JSON report is '<project_name>-<yyyy-mm-dd>T<HHmmss>+<UTC offset>-scan_report.json'.
For example: 'Demo App-2019-06-04T181226+0300-scan_report.json'
The following configuration parameters are available to control timeouts and file name format for the report:
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.
scanReportFilenameFormat: Controls filename format of a generated scan report.
NOTES:
The following is an example of a scan report with custom attributes available on the project:
{ "projectVitals": { "productName": "NuspecTest", "name": "NuspecTest_4", "token": "d38f6222562b403jiiojioc4e4cd19c7d54d6206b8bb5", "creationDate": "2019-02-27 13:52:46", "lastUpdatedDate": "2019-03-20 07:32:48" }, "libraries": [ { "keyUuid": "86d115e2-99ab-4jd-8092-f510b14fe949", "keyId": 35111144, "name": "microsoft.aspnetcore.server.kestrel.transport.abstractions.2.1.3.nupkg", "groupId": "", "artifactId": "microsoft.aspnetcore.server.kestrel.transport.abstractions.2.1.3.nupkg", "version": "", "sha1": "b1ef47c06e9e884doijooeafafafs0dfc83f3", "type": "UNKNOWN_ARTIFACT", "licenses": [], "vulnerabilities": [], "matchType": "SHA1", "customAttributeValues": [ { "contextName": "eRez-wss", "context": "Organizational", "contextId": "18945", "attr1": "rfv", "contextToken": "88cd28476aec411bjojojojojoi0283068a4632a4eae439bf70e691" } ], "policyDetails": { "policyName": "", "status": "no policy applied" } }, { "keyUuid": "018fijo9-aa6c-4118-bl[[l-b0b918b64311", "keyId": 35109719, "name": "microsoft.aspnetcore.2.1.4.nupkg", "groupId": "", "artifactId": "microsoft.aspnetcore.2.1.4.nupkg", "version": "", "sha1": "0706d598c463aede3fjojoioiioj5810q3tq3t4371a935e9df92a5", "type": "UNKNOWN_ARTIFACT", "licenses": [], "vulnerabilities": [], "matchType": "SHA1", "customAttributeValues": [ { "contextName": "eRez-wss", "context": "Organizational", "contextId": "18945", "attr1": "edc", "contextToken": "88cd28476aec4d68e411b02808a4632a4eae439bf70e691" } ], "policyDetails": { "policyName": "", "status": "no policy applied" } }, { "keyUuid": "b3c82c1a-8864-4842-bqwer-193df8683f04", "keyId": 35111034, "name": "system.memory.4.5.0.nupkg", "groupId": "System.Memory", "artifactId": "system.memory.4.5.0.nupkg", "version": "4.5.0", "sha1": "5835a676479b3e6a32167606f6", "type": "NUGET_PACKAGE_MODULE", "languages": "Nuget", "references": { "url": "https://api.nuget.org/packages/system.memory.4.5.0.nupkg", "homePage": "https://dot.net/", "genericPackageIndex": "https://api.nuget.org/packages/System.Memory/4.5.0" }, "licenses": [ { "name": "MIT", "url": "http://www.opensource.org/licenses/MIT", "profileInfo": { "copyrightRiskScore": "THREE", "patentRiskScore": "ONE", "copyleft": "NO", "royaltyFree": "YES" }, "referenceType": "NuGet package (details available in nuget gallery)", "reference": "https://github.com/dotnet/corefx/blob/master/LICENSE.TXT" } ], "vulnerabilities": [], "matchType": "SHA1", "customAttributeValues": [], "policyDetails": { "policyName": "mit", "status": "reject" } }, { "keyUuid": "5d63e066-b54f-43c3-b254", "keyId": 22769402, "name": "microsoft.aspnet.razor.3.2.3.nupkg", "groupId": "Microsoft.AspNet.Razor", "artifactId": "microsoft.aspnet.razor.3.2.3.nupkg", "version": "3.2.3", "sha1": "2cfd6d2ea3eb89362fa21a9b47", "type": "NUGET_PACKAGE_MODULE", "languages": "Nuget", "references": { "url": "https://api.nuget.org/packages/microsoft.aspnet.razor.3.2.3.nupkg", "genericPackageIndex": "https://api.nuget.org/packages/Microsoft.AspNet.Razor/3.2.3" }, "licenses": [ { "name": "Microsoft .NET Library", "url": "http://microsoft.com/web/webpi/eula/aspnetcomponent_rtw_enu.htm", "riskLevel": "unknown", "referenceType": "NuGet package (details available in nuget gallery)", "reference": "http://www.microsoft.com/web/webpi/eula/net_library_eula_ENU.htm" } ], "vulnerabilities": [], "matchType": "FILENAME", "customAttributeValues": [ { "contextName": "eRez-wss", "context": "Organizational", "contextId": "18945", "attr1": "1qa", "contextToken": "88cd28476aec4d68e429c181kjv3068a4632a4eae439bf70e691" }, { "contextName": "NuspecTest_4", "context": "Project", "contextId": "479597", "attr2": "2ws", "contextToken": "d38f6222562b46c2a8popb7f7c4e4cd19c7d54d6206b8bb5" }, { "contextName": "NuspecTest", "context": "Product", "contextId": "78835", "attr3": "3ed", "contextToken": "822ec9add1c84ebmomo20711cd41cmomo7a80de57c035a43" } ], "policyDetails": { "policyName": "policy1", "status": "reject" } }, { "keyUuid": "e178fa80-3196-49e8-8753emomoec8f", "keyId": 22769401, "name": "jquery.validation.1.11.1.nupkg", "groupId": "jQuery.Validation", "artifactId": "jquery.validation.1.11.1.nupkg", "version": "1.11.1", "sha1": "d6a4e4a2ccb2eaa203c0a99fb5168585d", "type": "NUGET_PACKAGE_MODULE", "languages": "Nuget", "references": { "url": "https://api.nuget.org/packages/jquery.validation.1.11.1.nupkg", "homePage": "http://bassistance.de/jquery-plugins/jquery-plugin-validation/", "genericPackageIndex": "https://api.nuget.org/packages/jQuery.Validation/1.11.1" }, "licenses": [ { "name": "MIT", "url": "http://www.opensource.org/licenses/MIT", "profileInfo": { "copyrightRiskScore": "THREE", "patentRiskScore": "ONE", "copyleft": "NO", "royaltyFree": "YES" }, "referenceType": "NuGet package (details available in nuget gallery)" } ], "vulnerabilities": [], "outdated": true, "matchType": "FILENAME", "outdatedModel": { "outdatedLibraryDate": "2013-03-25", "newestVersion": "1.17.0", "newestLibraryDate": "2018-01-25", "versionsInBetween": 6 }, "customAttributeValues": [], "policyDetails": { "policyName": "mit", "status": "reject" } }, { "keyUuid": "9abmo4d7-6112-47cd-98f26momo9264", "keyId": 22756758, "name": "entityframework.6.1.3.nupkg", "groupId": "EntityFramework", "artifactId": "entityframework.6.1.3.nupkg", "version": "6.1.3", "sha1": "b6e3e77f9b84b21b42cbdomo975ca81a", "type": "NUGET_PACKAGE_MODULE", "languages": "Nuget", "references": { "url": "https://api.nuget.org/packages/entityframework.6.1.3.nupkg", "genericPackageIndex": "https://api.nuget.org/packages/EntityFramework/6.1.3" }, "licenses": [ { "name": "Microsoft .NET Library", "url": "http://microsoft.com/web/webpi/eula/aspnetcomponent_rtw_enu.htm", "riskLevel": "unknown", "referenceType": "Project home page", "reference": "https://www.microsoft.com" } ], "vulnerabilities": [], "outdated": true, "matchType": "FILENAME", "outdatedModel": { "outdatedLibraryDate": "2015-03-10", "newestVersion": "6.2.0", "newestLibraryDate": "2017-10-26", "versionsInBetween": 0 }, "customAttributeValues": [], "policyDetails": { "policyName": "policy1", "status": "reject" } } ], "policyStatistics": { "totalApproved": 0, "totalRejected": 4, "totalReassigned": 0, "totalConditions": 0, "totalIssues": 0, "totalLibrariesAffected": 2 }, "vulnerabilityStatistics": { "low": 0, "medium": 0, "high": 0, "newVulnerabilities": 0, "oldVulnerabilities": 0, "ancientVulnerabilities": 0, "totalOutdated": 0, "totalVulnerableOutdated": 0, "totalLowVulnerabilities": 0, "totalMediumVulnerabilities": 0, "totalHighVulnerabilities": 0, "totalVulnerable": 0 } } |