Skip to main content

Repository Results View REST API

The Repository Results View REST API allows for requesting information about the components in a repository. Depending on the owner type this endpoint may return details of multiple repositories. This REST API endpoint is accessed with the View IQ Elements permission.

Warning

The experimental endpoint was updated during release 175 and is not compatible with older requests. Use the following endpoint going forward. For reference, the previous endpoint has been documented at the end of this page.

This is an experimental feature with the possibility of changing in the future.

Repository Results

Credentials with View IQ Elements are required to search for the components in a repository.

POST /api/experimental/repositories/{ownerType: repository_container|repository_manager|repository}/{ownerId}/results/details

Parameter

Values

ownerType

repository_container|repository_manager|repository

ownerId

See Firewall REST API for details on locating the owner id

Use the global id REPOSITORY_CONTAINER_ID for the repository container. This includes all configured repository managers

The search parameters must be included as the request body. See the reference section below for details on the search parameter.

{
    "page": 1,
    "pageSize": 10,
    "searchFilters": [
        {
            "filterableField": "COMPONENT_COORDINATES",
            "value": "ant"
        },
        {
            "filterableField": "REPOSITORY_ID",
            "value": "99285af9923c4ec1ae60529addab254f"
        }
    ],
    "sortFields": [
        {
            "sortableField": "QUARANTINE_TIME",
            "asc": false,
            "sortPriority": 1
        }
    ],
    "matchStateFilters": [
        "MATCH_STATE_EXACT"
    ],
    "violationStateFilters" : [
        "VIOLATION_STATE_OPEN"
    ],
    "threatLevelFilters": [
        0,
        10
    ],
    "aggregate": false
}

Completed curl request with escaped quotes

curl -X POST \
  -u admin:admin123 \
  -H "Content-Type: application/json" \
  "http://localhost:8070/api/experimental/repositories/repository_container/REPOSITORY_CONTAINER_ID/results/details" \
  -d "{\"page\": 1,\"pageSize\": 4, \"matchStateFilters\": [\"MATCH_STATE_ALL\"], \"violationStateFilters\": [\"VIOLATION_STATE_ALL\"], \"searchFilters\": [{\"filterableField\": \"REPOSIOTRY_MANAGER_ID\", \"value\": \"4ebc94d10f6b4f3dbc1a3375e2f3678\"}],\"sortFields\": [{\"sortableField\": \"POLICY_NAME\", \"asc\": false, \"sortPriority\": 1}]}"

Example Response

{
    "repositoryResultsDetails": [
        {
            "threatLevel": 7,
            "policyName": "Security-Medium",
            "repositoryManagerId": "6d27e83a8d5a4befa5f97d2a7f32b352",
            "repositoryId": "99285af9923c4ec1ae60529addab254f",
            "componentDisplayText": "ant : ant : 1.6.1",
            "pathname": "ant/ant/1.6.1/ant-1.6.1.jar",
            "componentIdentifier": {
                "format": "maven",
                "coordinates": {
                    "artifactId": "ant",
                    "classifier": "",
                    "extension": "jar",
                    "groupId": "ant",
                    "version": "1.6.1"
                }
            },
            "hash": "684aeca90db2a55234f5",
            "matchStateId": "exact",
            "quarantineTime": 1711040046780,
            "waived": false
        },
        {
            "threatLevel": 7,
            "policyName": "Security-Medium",
            "repositoryManagerId": "6d27e83a8d5a4befa5f97d2a7f32b352",
            "repositoryId": "99285af9923c4ec1ae60529addab254f",
            "componentDisplayText": "ant : ant : 1.6.1",
            "pathname": "ant/ant/1.6.1/ant-1.6.1.jar",
            "componentIdentifier": {
                "format": "maven",
                "coordinates": {
                    "artifactId": "ant",
                    "classifier": "",
                    "extension": "jar",
                    "groupId": "ant",
                    "version": "1.6.1"
                }
            },
            "hash": "684aeca90db2a55234f5",
            "matchStateId": "exact",
            "quarantineTime": 1711040046780,
            "waived": false
        }
    ],
    "hasNextPage": false
}

Repository results search parameter reference

The following are details on the search parameters used to filter repository results.

Page

The current page of the results. Use this field to iterate from one page to the next.

page : 1
Page size

The number of items returned per request.

pageSize : 10
Search filters

An array of search parameters may be included to narrow the results. The repository ID may be used to filter to a specific repository.

searchFilters : [ POLICY_NAME, QUARANTINE_TIME, COMPONENT_COORDINATES, REPOSITORY_MANAGER_ID, REPOSITORY_ID ]
Sort field

An array of sort parameters may be included and ordered by the provided priority.

sortFields : [ POLICY_THREAT_LEVEL, POLICY_NAME, COMPONENT_COORDINATES, QUARANTINE_TIME ]
Match state

See Component Identification for details on match states.

matchStateFilters : [ MATCH_STATE_ALL, MATCH_STATE_EXACT, MATCH_STATE_UNKNOWN ]
Violation state

Narrow results by the state of the violation.

violationStateFilters : [ VIOLATION_STATE_ALL, VIOLATION_STATE_NOT_VIOLATING, VIOLATION_STATE_OPEN, VIOLATION_STATE_QUARANTINED, VIOLATION_STATE_WAIVED ]
Threat level

Provide a range of lowest to highest threat level to focus your search results.

threatLevelFilters : [ 0, 10 ]
Aggregate results

Results may be aggregated together to simplify navigating components in the repository.

  • true: component is listed once with it's highest policy violation

  • false: every violation is listed for the component

aggregate : [ true, false ]

Deprecated as of release 175

This endpoint has been updated as of release 175. The below request is for Lifecycle instances prior to this release.

POST Repository Results - deprecated

To get the details about the repository results, you can issue a POST request to the following path:

POST /api/experimental/repositories/{repositoryId}/results/details

Include JSON data specifying the page, page size, match state filters, violation state filters, search filters and sort fields.

Example Request - deprecated

For example, you could send a JSON like this:

{
  "page": 1,
  "pageSize": 10,
  "matchStateFilters": [
    "MATCH_STATE_ALL"
  ],
  "violationStateFilters": [
    "VIOLATION_STATE_ALL"
  ],
  "searchFilters": [
    {
      "filterableField": "POLICY_NAME",
      "value": "Policy Name Test"
    }
  ],
  "sortFields": [
    {
      "sortableField": "POLICY_NAME",
      "asc": false,
      "sortPriority": 1
    }
  ]
}

If your request was successfully processed, the system will respond with the HTTP response code 200 OK and the json response will look like the following:

[
  {
    "threatLevel": 1,
    "policyName": "Architecture-Cleanup",
    "componentDisplayText": "ant : ant : 1.6.3",
    "pathname": "org/springframework/spring-core/5.3.6/spring-core-5.3.6.jar",
    "componentIdentifier": {
      "format": "maven",
      "coordinates": {
        "artifactId": "spring-core",
        "classifier": "",
        "extension": "jar",
        "groupId": "org.springframework",
        "version": "5.3.6"
      }
    },
    "hash": "8f91f60f628075701fde",
    "matchStateId": "exact",
    "quarantineTime": null,
    "waived": false
  },
  {
    "threatLevel": 7,
    "policyName": "Security-Medium",
    "componentDisplayText": "ant : ant : 1.6.3",
    "pathname": "org/springframework/spring-core/5.3.6/spring-core-5.3.6.jar",
    "componentIdentifier": {
      "format": "maven",
      "coordinates": {
        "artifactId": "spring-core",
        "classifier": "",
        "extension": "jar",
        "groupId": "org.springframework",
        "version": "5.3.6"
      }
    },
    "hash": "8f91f60f628075701fde",
    "matchStateId": "exact",
    "quarantineTime": null,
    "waived": false
  }
]