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 NameValueComments

agent

GenericIf you're developing your own plugin / agent let us know at support@whitesourcesoftware.com
agentVersion1.0Might change in the future
typeEither UPDATE or CHECK_POLICIES or CHECK_POLICY_COMPLIANCEMight change in the future
tokenYour organization API tokenGet it from your account administrator
timeStampLong. Number of milliseconds since the Java epoch
diffJSON encoded array of AgentProjectInfoSee 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 NameValue
productName or token of the product to be matched to in the WhiteSource dashboard
productVersionVersion of the product above. This can be used the maintain different versions of the same product
requesterEmailThe 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
forceCheckAllDependenciesDefault 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 NameValueComments
envelopeVersionString: "1.0"


status

Integer:

  • 1 - success
  • 2 - bad request
  • 3 - server error

message

String: "ok" - on success, descriptive error message in case of error


dataString: 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.

FieldTypeComments
coordinatesCoordinatesproject coordinates
parentCoordinatesCoordinatesparent project coordiantes
projectTokenStringproject unique token (ask your admin)
dependenciesArray of DependencyInfoopen 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.

FieldTypeComments
groupIdStringOptional.
artifactIdStringMandatory. Project name or id
versionStringOptional.

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:

FieldTypeComments
groupIdStringOptional.
artifactIdStringMandatory, file name or artifact id.
versionString

Optional.

typeStringOptional.
classifierStringOptional.
scopeStringOptional.
sha1StringSHA-1 hash of the physical file (40 chars)
otherPlatformSha1StringOptional, SHA-1 hash of the physical file on a different OS (replacing new line of Windows and Unix or vice versa)

systemPath

StringOptional, location in your local machine of the file
licensesArrayOptional, an array of license names
copyrightsArrayOptional, 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.