Documentation Nexus IQ Server 1.22

Our documentation site has moved. For the most current version, please see http://help.sonatype.com

23.5. Violation REST API (v2)

The Policy Violation REST APIs allow you to access and extract policy violations gathered during the evaluation of applications. In most cases the desire for getting to this data is to integrate into other tools your company may have. For example you may have a specific dashboard or reporting application that should have this data.

Whatever the case, just as with the other REST APIs, this is all done using REST API calls. For accessing policy violation information the following API is used:

GET
Used to retrieve policy information, such as a list of policy ids as well as a list of violations based on a specific Policy ID, or list of IDs.

As mentioned previously, we will provide both the API, as well as examples using the HTTP client cURL. This is only for demonstration purposes and displaying the necessary input, and desired output.

Additionally, to help demonstrate this, we’ve approached this in a step-by-step manner that will start with gathering policy ids, and then requesting the violations.

Before You Get Started

As with the other REST APIs, you will need a username and password to interface with the IQ Server. In addition, because access to this data is granted based on the roles (permissions) you have set up, you may wish to create one specifically for this process.

Other than this, the only piece you may need in order to follow along with our instructions is cURL, or a comparable HTTP client.

Step 1 - Get the Policy IDs. To access policy violation information you need the Policy ID(s). For this reason, we start with the GET API call…

GET  /api/v2/policies/

which will return a list of all Policy IDs. To follow along using cURL, enter the following command:

curl -u admin:admin123 -X GET 'http://localhost:8070/api/v2/policies'

The action above will produce a list of your policies in a JSON format. Here is an example of what might be returned.

{
    "policies": [
        {
            "id": "6984017845c645b0ad0c95401ad4f17d",
            "name": "My Application Policy",
            "ownerId": "36d7e629462a4038b581488c347959bc",
            "ownerType": "APPLICATION",
            "threatLevel": 5,
            "policyType": "quality"
        },
    ]
}
[Note]

As you can see above, we’ve used the admin user which is shipped with the IQ Server, as well as the default IQ Server location. The user you use may differ depending on your configuration.

id
This is the internal id for the policy.
name
This is the name of the policy, and is visible in the IQ Server GUI.
ownerId
This is the internal id for the organization or application that the policy resides in, and is not visible within the IQ Server GUI.
ownerType
This indicates whether the policy is for an organization or application.
threatLevel
This is the threat level that is set for the policy.
policyType
This is the policy type, which is based on the conditions used in the policy.
[Tip]

In many cases, you will have many policies, especially if you are retrieving information for an account that has access to many applications and/or organization.

Step 2 - Get the Policy Violations. Now that you have the Policy IDs, they can be used to gather a list of policy violations. To do this, you will need the Policy IDs you retrieved from step one. For example:

"id": "6984017845c645b0ad0c95401ad4f17d"
[Note]

Policy IDs are unique, and what is used above is just an example.

Slightly different from before, we will use the GET API call…

GET /api/v2/policyViolations?p=policyid1

which passes a simple query for Policy IDs. For each policy we want to retrieve violations for, we will include that ID. If desired we can retrieve violations for multiple Policy IDs. To do this, just make sure you add &p="The Policy ID" for each policy you want included. Here is an example of the API with the Policy ID we retrieved:

GET /api/v2/policyViolations?p=6984017845c645b0ad0c95401ad4f17d

Putting this all together, and using our cURL example, you should enter the following command:

curl -u admin:admin123 -X GET 'http://localhost:8070/api/v2/policyViolations?p=6984017845c645b0ad0c95401ad4f17d'

If your query was successful, the system will respond with something like this:

{
   "applicationViolations":[
      {
         "application":{
            "id":"529b7f71bb714eca8955e5d66687ae2c",
            "publicId":"MyAppID1",
            "name":"MyApplications",
            "organizationId":"36d7e629462a4038b581488c347959bc",
            "contactUserName":null
         },
         "policyViolations":[
            {
               "policyId":"6984017845c645b0ad0c95401ad4f17d",
               "policyName":"Security-High",
               "stageId":"build",
               "reportUrl":"ui/links/application/MyAppID1/report/c0ddefc4512f42d0bcbe29029e2be117",
               "threatLevel":9,
               "constraintViolations":[
                  {
                     "constraintId":"19011de290b147a38c820ad7bd5c653d",
                     "constraintName":"CVSS >=7 and <10",
                     "reasons":[
                        {
                           "reason":"Found 2 Security Vulnerabilities with Severity >= 7"
                        },
                        {
                           "reason":"Found 4 Security Vulnerabilities with Severity < 10"
                        },
                        {
                           "reason":"Found 4 Security Vulnerabilities with Status OPEN"
                        }
                     ]
                  }
               ],
               "component":{
                  "hash":"384faa82e193d4e4b054",
                  "componentIdentifier":{
                     "format":"maven",
                     "coordinates":{
                        "artifactId":"tomcat-util",
                        "classifier":"",
                        "extension":"jar",
                        "groupId":"tomcat",
                        "version":"5.5.23"
                     }
                  },
                  "proprietary":false
               }
            }
         ]
      }
   ]
}

And there you have it, you’ve just retrieved policy violations. Below, each of the categories of data that is returned, as well as each field, have been described.

application

This category contains specific information about the application.

id
This is the internal id.
publicId
This is the application ID. In the IQ Server GUI this is represented by the "Application" field.
name
This is the name of the application. In the IQ Server GUI this corresponds to the "Application Name" field.
organizationId
This is the internal id for the organization that the application resides in, and is not visible within the IQ Server GUI.
contactUserName
This is typically the person in charge of the application. In the IQ Server GUI, it corresponds to the contact field for the application.
policyViolations

This is a subcategory of the application, and provides specific information about the policy and corresponding violations that were found.

policyId
This is the internal id for the policy.
policyName
This is the name of the policy, and is visible in the IQ Server GUI.
stageId
This is the stage in which the policy violation occurred in. It is displayed in various places within the IQ Server GUI, including the associated Application Composition Report.
reportUrl
This is the URL to the Application Composition Report associated with the evaluation that found the listed policy violations.
threatLevel
This the threat level of the policy that was violated.
constraintViolations

This is a subcategory for Policy Violations, and includes all information related to specific constraint that was violated.

constraintId
This is the internal id for the constraint, and is not visible in the IQ Server GUI, or in the associated Application Composition Report.
constraintName
This is the name of the constraint and is visible in the policy area where the policy was created (i.e either the organization or application). It is also displayed in the Application Composition Report and various tools that connect to the IQ Server.
reasons

This is a subcategory of Constraint Violations, and gives the reason why the violation occurred.

reason
The reason is formed by the value(s) for the condition(s) violated. Conditions are visible where the policy was created (i.e either the organization or application). It is also displayed in the Application Composition Report and various tools that connect to the IQ Server.
component
Component is a subcategory of Policy Violations, and includes information about the component(s) causing the violation to occur.
[Note]

The component field only refers to a single component. If another component violates the same policy, another entry for that in "policyViolations" would be present.

hash
This is the hash value for the component. For example, in the case of Java components, this would be matched to a Java repository (e.g. Central). If you have proprietary components configured, it would be matched against your list of proprietary components.
componentIdentifier

This is simply a container for the component information. It will always include the format and the coordinates.

format
This is the format the component is in, and will determine what type of coordinate information is displayed.
coordinates
This will depend on the format. An example would be Maven, which uses a G : A : E : C : V (Group, Artifact Id, Extension, Classifier, and Version) for the component. In this example, the fields provided are: groupId, artifactId, and version.