Query Issues by Taxonomy

Overview

Taxonomies categorize issues based on their issue type. Coverity on Polaris provides several taxonomies for categorizing issues in different ways. Some taxonomies are based on third-party data such as 'OWASP Web Top 10' and 'CWE Top 25' while others are based on data unique to Coverity on Polaris such as 'Issue Kind'.

The currently defined taxonomies in Coverity on Polaris can be retrieved like this:

 curl -X GET "https://subdomain.cop.blackduck.com/api/taxonomy/v0/taxonomies?page[limit]=10"\
-H "accept: application/json"\
-H 'Authorization: Bearer {JWT}'

To use this example:

Replace subdomain in the URL with the Coverity on Polaris domain that you use.
Insert your JWT at the end of the request.
Depending the client you use, you might need to URL-encode the parameter ?page[limit]=10 as shown, so that it reads: ?page%5Blimit%5D=10.

Here is an example of JSON data returned from the /taxonomies endpoint:

   {
    "data":[
        {
            "id":"ade7719e-57be-413a-9120-bfed63d2dbf8",
            "taxonomy":{
                "taxa": [
                    ...
                ],
                ...
            },
            "taxonomy-type":"cwe",
            ...
        },
        ...
    ]
}

The result contains an array of taxonomy definitions. Each taxonomy definition has the attributes id and taxonomy-type, either of which can be used to identify a taxonomy when making issue queries.

In other words, taxonomy-type values can be parsed as data[*].taxonomy-type while taxonomy id values can be parsed as data[*].id.

It's best to use taxonomy-type to identify taxonomies in scripts and queries. Taxonomy id changes when taxonomies are updated, so it is inconsistent across deployments.

Some example taxonomy-types are:

cwe, issue-kind, owasp, recognized-priority-list, severity, technical-risk

Group by Taxonomy

Counts of issues can be grouped by the main categories in a taxonomy specified by 'taxonomy-type' with:

group-by=[issue][taxonomy][taxonomy-type][{taxonomy-type}]

Example:

https://subdomain.cop.blackduck.com/api/query/v1/roll-up-counts?project-id=ebd1777f-3117-4511-8c2f-fb0258907b8f&branch-id=b2cf3913-8b5e-4d5f-880c-172d4de69db3&group-by=[issue][taxonomy][taxonomy-type][cwe]&page[limit]=25

Filter by Taxonomy

Lists of issues can be filtered to include only issues in a taxonomy specified by 'taxonomy-type' with:

filter[issue][taxonomy][taxonomy-type][$eq]={taxonomy-type}

Example:

https://subdomain.cop.blackduck.com/api/query/v1/issues?project-id=0c0bb76a-d43a-4406-8a37-9d27514dd043&branch-id=d618c766-6810-4949-b244-f15fe0238a2d&filter[issue][taxonomy][taxonomy-type][$eq]=cwe&page[limit]=25

Filter by Taxon

Lists of issues can be filtered by taxonomy to include only those that share a single category.

A 'taxon' (plural 'taxa') is a category or classification group within a taxonomy. When using the taxonomies endpoint to view taxonomy definitions as JSON data, the taxa that make up the taxonomy can be parsed as follows: data[*].taxonomy.taxa. Lists of issues can be filtered to include only issues categorized under a specific taxon, using this syntax:

filter[issue][taxonomy][taxonomy-type][{taxonomy-type}][taxon][$eq]={taxon-id}

Example:

 https://subdomain.cop.blackduck.com/api/query/v1/issues?project-id=ebd1777f-3117-4511-8c2f-fb0258907b8f&branch-id=b2cf3913-8b5e-4d5f-880c-172d4de69db3&filter[issue][taxonomy][taxonomy-type][cwe][taxon][$eq]=1000&page[limit]=25

For a complete list of available filters and group-bys, refer to API Services.