Agents API

Overview

The API is just a HTTP endpoint implementing a JSON speaking web service. Communication is secured with SSL like the service itself.

At the time of writing, the API support only two methods:

Check Policies - check if given open source libraries conforms with company policy.
Update Inventory - update open source inventory.

View the source at GitHub: https://github.com/whitesource/agents.

Endpoint

The service listens on saas.whitesourcesoftware.com/agent on both HTTP and HTTPS protocols.

Only POST requests are expected.

Request payload should have:

ContentType=application/x-www-form-urlencoded
charset=UTF-8

Request Format

Every such request has mandatory fields and optional fields.

Mandatory Fields

Param Name	Value	Comments
agent	Generic	If you're developing your own plugin / agent let us know at support@whitesourcesoftware.com
agentVersion	1.0	Might change in the future
type	Either UPDATE or CHECK_POLICIES or CHECK_POLICY_COMPLIANCE	Might change in the future
token	Your organization API token	Get it from your account administrator
timeStamp	Long. Number of milliseconds since the Java epoch
diff	JSON encoded array of AgentProjectInfo	See below the spec for data types

Example:

type=UPDATE&agent=generic&agentVersion=1.0&token=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa&timeStamp=1514186516157&diff=
[
    {
       "coordinates":{
          "artifactId":"project_name",
          "version":"project_version"
      },
        "dependencies": [
        {
          "artifactId": "aopalliance-1.0.jar",
          "sha1": "0235ba8b489512805ac13a8f9ea77a1ca5ebe3e8",
          "otherPlatformSha1": "06ff7ef5e2dfd459e7b20edafe5f1376ae4a1f05",
          "systemPath": "C:\\WhiteSource\\FS-Agent\\Jars\\aopalliance-1.0.jar",
          "optional": false,
          "children": [],
          "exclusions": [],
          "licenses": [],
          "copyrights": [],
          "filename": "aopalliance-1.0.jar",
          "checksums": {
            "SHA1": "0235ba8b489512805ac13a8f9ea77a1ca5ebe3e8",
            "SHA1_OTHER_PLATFORM": "06ff7ef5e2dfd459e7b20edafe5f1376ae4a1f05"
          }
        },
        {
          "artifactId": "commons-beanutils-1.8.0.jar",
          "sha1": "0c651d5103c649c12b20d53731643e5fffceb536",
          "otherPlatformSha1": "0f52d720a1be77c67669b88e74448f3b2dae6624",
          "systemPath": "C:\\WhiteSource\\FS-Agent\\Jars\\commons-beanutils-1.8.0.jar",
          "optional": false,
          "children": [],
          "exclusions": [],
          "licenses": [],
          "copyrights": [],
          "filename": "commons-beanutils-1.8.0.jar",
          "checksums": {
            "SHA1": "0c651d5103c649c12b20d53731643e5fffceb536",
            "SHA1_OTHER_PLATFORM": "0f52d720a1be77c67669b88e74448f3b2dae6624"
          }
        }
      ]
    }
]

Optional Fields

Param Name	Value
product	Name or token of the product to be matched to in the WhiteSource dashboard
productVersion	Version of the product above. This can be used the maintain different versions of the same product
requesterEmail	The provided email will be matched with an existing WhiteSource account. Requests for new libraries will be created with the matched account as the requester.
projectToken	Unique identifier of the White Source project to update. If omitted, default naming convention will apply. No productToken is allowed
forceCheckAllDependencies	Default value is: false - policies will be checked only for new dependencies introduced to the WhiteSource projects.Only works when CHECK_POLICY_COMPLIANCE

For new plugins the CHECK_POLICY_COMPLIANCE should be used instead of CHECK_POLICIES, to achieve the same functionality as CHECK_POLICIES just set the forceCheckAllDependencies to false

Response Format

Every response from the service comes in encoded in JSON with a constant structure consisting of fixed part, envelope, and a dynamic part.

The envelope format is:

Param Name	Value	Comments
envelopeVersion	String: "1.0"
status	Integer: 1 - success 2 - bad request 3 - server error
message	String: "ok" - on success, descriptive error message in case of error
data	String: dynamic JSON object

Example - response for the Update request type :

{
"envelopeVersion":"1.0",
"status":1,
"message":"ok",
"data":
  "{
    "organization":"1234Try",
    "updatedProjects":["jboss-as-kitchensink - 7.1.1"],
    "createdProjects":[]
  }"
}

Example - response for the check policies request type :

{
"envelopeVersion":"1.0",
"status":1,
"message":"ok",
"data":
	{
	  "organization": "Testing",
	  "existingProjects": {},
	  "newProjects": {
		"My Awesome Project:1.0.0": {
		  "children": [
			{
			  "resource": {
				"displayName": "Sprite.dll",
				"link": "http://localhost:8081/Wss/WSS.html#!libraryDetails;idu003d13168231",
				"licenses": [],
				"sha1": "afadd9398b54d2818392e250804adff854cf6189",
				"vulnerabilities": []
			  },
			  "policy": {
				"displayName": "no mit",
				"filterType": "LICENSE",
				"filterLogic": "unknown|MIT",
				"actionType": "Reject",
				"projectLevel": false
			  },
			  "children": []
			}
		  ]
		}
	  },
	  "projectNewResources": {
		"My Awesome Project:1.0.0": [
		  {
			"displayName": "Sprite.dll",
			"link": "http://localhost:8081/Wss/WSS.html#!libraryDetails;idu003d13168231",
			"licenses": [],
			"sha1": "afadd9398b54d2818392e250804adff854cf6189",
			"vulnerabilities": []
		  }
		]
	  }
	}
}

Data Types

The diff parameter is the actual data regarding the projects and dependencies, it's a JSON-ified collection of AgentProjectInfo objects.

Example:

[
    {
      "coordinates":{
        "artifactId":"My Project",
        "version":""
      },
      "dependencies":[
        {
          "artifactId":"Sprite.cpp",
          "sha1":"afadd9398b54d2818392e250804adff854cf6189",
          "otherPlatformSha1":"7063a3ba553170f309957acd2b7022fcd830dc2e",
          "systemPath":"C:\\WhiteSource\\quirkysoft\\Sprite.cpp",
          "optional":false,
          "children":[],
          "exclusions":[],
          "licenses":[
            "GPL 3.0"
          ],
          "copyrights":[
            {
              "copyright":"Copyright (C) 2007,2008 Richard Quirk",
              "line": 2
            }
          ],
          "lastModified":"Feb 1, 2015 9:31:31 AM"
        }
      ]
    }
]

There are few data types used throughout the API. Their structure is as follows:

AgentProjectInfo

View source on GitHub: https://github.com/whitesource/agents/blob/master/wss-agent-api/src/main/java/org/whitesource/agent/api/model/AgentProjectInfo.java.

Encapsulates project identification + open source usage of a SW project.

Field	Type	Comments
coordinates	Coordinates	project coordinates
parentCoordinates	Coordinates	parent project coordiantes
projectToken	String	project unique token (ask your admin)
dependencies	Array of DependencyInfo	open source dependencies

When using coordinates (not project token) WhiteSource will automatically create a project if non exists.

Important

At lease one of coordinates or projectToken must be provided.

Coordinates

View source on GitHub: https://github.com/whitesource/agents/blob/master/wss-agent-api/src/main/java/org/whitesource/agent/api/model/Coordinates.java.

Maven-like coordinates.

Field	Type	Comments
groupId	String	Optional.
artifactId	String	Mandatory. Project name or id
version	String	Optional.

DependencyInfo

View source on GitHub: https://github.com/whitesource/agents/blob/master/wss-agent-api/src/main/java/org/whitesource/agent/api/model/DependencyInfo.java.

Information to identify an open source component:

Field	Type	Comments
groupId	String	Optional.
artifactId	String	Mandatory, file name or artifact id.
version	String	Optional.
type	String	Optional.
classifier	String	Optional.
scope	String	Optional.
sha1	String	SHA-1 hash of the physical file (40 chars)
otherPlatformSha1	String	Optional, SHA-1 hash of the physical file on a different OS (replacing new line of Windows and Unix or vice versa)
systemPath	String	Optional, location in your local machine of the file
licenses	Array	Optional, an array of license names
copyrights	Array	Optional, an array of CopyrightInfo objects with two fields: 1. copyright - the copyright notice. 2. line - the line number in the file (relevant only for source files).

Mandatory fields

Dependency management systems like maven uses coordinates to identify libraries.

Use them if you have them. If not, sha1 field becomes mandatory.