Uploading Update Requests via the Mend API - Unified Agent

Summary

Organization administrators are able to upload update requests to the Mend Servers using Admin → Upload Update Request. This can also be done with the API, which allows non-admin users to complete this step and makes it possible to include uploading update requests as part of an automated process like a pipeline. Another way you can upload an update request is with the Unified Agent. This is explained in Unified Agent: Advanced Topics - Uploading an Offline Request File; however, this article will describe how to format the update request correctly and run the API successfully.

Setup

After running a scan, the results of the scan are put into a JSON format called an “update request”. This is then sent to Mend servers when the Unified Agent parameter ‘offline’ is set to ‘false’ (default). If you set “offline=true” in your configuration file, the Unified Agent stores the update request in a file in the “whitesource” folder of your directory where you ran the scan.

The API Request

The API request to upload an update request is as follows:

URL: https://saas.whitesourcesoftware.com/agent (change this to saas-eu, app, or app-eu, or your dedicated instance URL accordingly)

Method: POST

Headers: Charset = utf-8, Content-Type = application/x-www-form-urlencoded

Body:

CODE

type=UPDATE
&updateType=OVERRIDE
&agent=fs-agent
&agentVersion=x.x
&token=<your-org-token>
&userKey=<your-user-key>
&timeStamp=123
&diff=[{
  "coordinates": { "artifactId": "My Project"},
  "dependencies": [{
    //dependency information
  }]
}]

NOTE: Not everything in the API request is in the JSON format (everything under the “diff” section is. Therefore some re-formatting will be required. (See below for a powershell script that will allow you to generate the body).

Once you send all of this information to the appropriate Mend server, the appropriate project will be updated with the given information, and you will be able to see the vulnerability information in the UI.