API for Component Inventory

Table of Contents

API V2
API V1
- Request Report Generation
- Retrieve the Report
  - Example Request
  - Example Response

Need help?

Schedule a consultation with an Azul performance expert.

The Component Inventory API allows you to create and download reports to get insights into what components are used in your Java application(s).

Component Inventory reports can be grouped by tag to break down areas of ownership and logically combine differentiated services, build versions, regions, or other information.

Reports are generated asynchronously. By using the schedule endpoint, a task to generate a report is created. In response, you get a unique report identifier. With this identifier, you can retrieve the report.

API V2

Request Parameters

You can extend the request with a filter for one or more fields.

Argument	Default	Description
reportName	string	Name of the report.
from	string	Relative or absolute time that will be applied to the firstSeen timestamp of the AppEnv. See API Date Filter Format.
to	string	Relative or absolute time that will be applied to the lastSeen timestamp of the AppEnv. See API Date Filter Format.
filter	list	List of filters as described in the Filter Rules.
sortBy	list	List of sorting conditions as described in the Sorting Rules.

Argument

Default

Description

reportName

string

Name of the report.

from

string

Relative or absolute time that will be applied to the firstSeen timestamp of the AppEnv. See API Date Filter Format.

string

Relative or absolute time that will be applied to the lastSeen timestamp of the AppEnv. See API Date Filter Format.

filter

list

List of filters as described in the Filter Rules.

sortBy

list

List of sorting conditions as described in the Sorting Rules.

Filter Rules

Operand Applicable Fields Description

Operand	Applicable Fields	Description
`=`	AppEnv, componentName, componentVersion, tags.A, tags.B, tags.xxx	Filters on exact equality. Returns a list of all AppEnv(s)/components containing, e.g., the tag `{tag.xxx:value}`.
`!=`	AppEnv, componentName, componentVersion, tags.A, tags.B, tags.xxx	Filters on exact inequality. Returns a list of all AppEnv(s)/components that do not contain the tag, e.g., `{tag.xxx:value}`.
`= null`	cveId, tags.A, tags.B, tags.xxx	Returns a list of all unaffected components, and a list of all AppEnv(s)/components that do not contain, e.g., the tag `tag.xxx`.
`!= null`	cveId, tags.A, tags.B, tags.xxx	Returns a list of all vulnerable components, and a list of all AppEnv(s)/components containing the tag, e.g., `tag.xxx`.
`IN ('A', …)`	AppEnv, componentName, componentVersion, tags.A, tags.B, tags.xxx	Filters on exact equality.
`<=`, `>=`, `<`, `>`	score, componentVersion	Use this filter to compare numbers (`score`) or the string representation of versions (`componentVersion`).
`CONTAINS '…'`	AppEnv, componentName, componentVersion, tags.A, tags.B, tags.xxx	Filters on the fields containing the given value.

=

AppEnv, componentName, componentVersion, tags.A, tags.B, tags.xxx

Filters on exact equality. Returns a list of all AppEnv(s)/components containing, e.g., the tag {tag.xxx:value}.

!=

AppEnv, componentName, componentVersion, tags.A, tags.B, tags.xxx

Filters on exact inequality. Returns a list of all AppEnv(s)/components that do not contain the tag, e.g., {tag.xxx:value}.

= null

cveId, tags.A, tags.B, tags.xxx

Returns a list of all unaffected components, and a list of all AppEnv(s)/components that do not contain, e.g., the tag tag.xxx.

!= null

cveId, tags.A, tags.B, tags.xxx

Returns a list of all vulnerable components, and a list of all AppEnv(s)/components containing the tag, e.g., tag.xxx.

IN ('A', …)

AppEnv, componentName, componentVersion, tags.A, tags.B, tags.xxx

Filters on exact equality.

<=, >=, <, >

score, componentVersion

Use this filter to compare numbers (score) or the string representation of versions (componentVersion).

CONTAINS '…'

AppEnv, componentName, componentVersion, tags.A, tags.B, tags.xxx

Filters on the fields containing the given value.

Sorting Rules

It is possible to sort by AppEnv, componentName, componentVersion, firstSeen, lastSeen. The default sort is:

 "sortBy": [
    "AppEnv=ASC",
    "componentName=ASC",
    "componentVersion=DESC"
]

Response Structure

 {
  "reportName": "<string>",
  "reportId": "<string>",
  "state": "<string>",
  "userId": "<string>",
  "params": {
    "resolvedFrom": "<date & time ISO 8601 string>",
    "resolvedTo": "<date & time ISO 8601 string>",
    "from": "<date & time string>",
    "to": "<date & time string>",
    "filter": [<List of "field cindition value">],
    "sortBy": [<List of "field = direction">]
  },
  "stateMessages": [<List of string>],
  "requestTime": "<date & time ISO 8601 string>",
  "startTime": "<date & time ISO 8601 string>",
  "finishTime": <date & time ISO 8601 string>,
  "data": [ <List of "Vulnerability Detection" objects:
    {
      "AppEnv": "<string>",
      "componentName": "<string>",
      "componentVersion": "<string>",
      "firstSeen": "<date & time ISO 8601 string>",
      "lastSeen": "<date & time ISO 8601 string>",
      "tags": {
        "<string>": ["<string>", "<string>", "<string>"]
        "<string>": ["<string>", "<string>"],
        "<string>": ["<string>"],
        ...
      }
    }
  >],
  "totalCount": <numeric>,
  "afterToken": "<string>"
}

API V1

Request Report Generation

You can request the generation of a report with a POST call to https://YOUR_ENDPOINT.azul.com/public/component/report/schedule and a set of parameters.

Request Parameters

Argument Default Description

filter

array[string]

SQL-based filters applied to data collected from virtual machines. The fields used to filter the data are presented in the data items of the response.

Supported operations:

field = literal
field = null
field != literal
field != null
field < literal
field <= literal
field > literal
field >= literal
field LIKE regexp
field CONTAINS literalSubstring
field IN (literal1, literal2,…literalN)
field RANGE (literalLow, literalHigh)

groupBy

array[string]

List of fields by which the components (name + version) are grouped. The order of the fields directly affects the result of the grouping. The values of the groupBy fields are presented in the data items of the response. In addition, the count field corresponding to the number of VMs included in each group is returned.

Format: <field_name>.

Note	The count field can be used to sort data, for example, using `count=ASC`.

Note	To group by time period, use the keywords `year`, `month`, `week`, or `day`. When using `week`, the week number of the year is used (`Calendar.WEEK_OF_YEAR`).

sortBy

array[string]

A set of fields and the desired sort order for their values.

Format: <field_name>=<sort_order>.

Sort order values:

ASC - ascending
DESC - descending

startTime

string

Relative or absolute time to get components detected by AVD based on VMs that are still running after (or equal to) the provided startTime. See API Date Filter Format.

Default value: 3m.

endTime

string

Relative or absolute time to get components detected by AVD based on VMs that are not started after the provided endTime. See API Date Filter Format.

details

boolean

Whether to include in the report a set of virtual machine IDs containing a particular detected component (name + version).

Default value: false.

Example Request

 curl -X 'POST' \
  'https://YOUR_ENDPOINT.azul.com/public/component/report/schedule' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
  "filter": [
    "tags.owner CONTAINS 'admin'",
    "state != 'OFFLINE'"
  ],
  "groupBy": [
    "state",
    "agentVersion"
  ],
  "sortBy": [
    "componentName=ASC",
    "tags.owner=DESC"
  ],
  "startTime": "2022-05-01T12:43:50.999",
  "endTime": "1d",
  "details": false
}'

Example Response

In response, you get a reportId that can be used with the GET endpoint to retrieve the report.

 {
  "reportId": "f12ba5df-0673-4917-92ce-4f6c84a3ace8",
  "userId": "...",
  "parameters": {
    "filter": [
      "tags.owner CONTAINS 'admin'",
      "state != 'OFFLINE'"
    ],
    ...
    "details": false
  },
  "state": "PROCESSING",
  "requestTime": 1682510562745
}

Retrieve the Report

You can retrieve a report with a GET call to https://YOUR_ENDPOINT.azul.com/public/component/report/YOUR_REPORT_ID.

The response must be checked to define if the data is available, based on the following possible return data:

state: State of the request, one of the following options:
- PROCESSING
- SUCCEEDED
- FAILED
- PARTIALLY_FAILED
- TIMED_OUT
summary: More info related to the state.
errors: Errors while creating the report (if applicable).

Large reports are split into pages (up to 5.5MB per page). You can find the total number of pages in the response and use this value to retrieve all the report pages.

Note	Regardless of whether a report is generated successfully or not, when the generation is finished, at least one page of the report is available for retrieval.

Example Request

 curl -X 'GET' \
  'https://YOUR_ENDPOINT.azul.com/public/component/report/YOUR_REPORT_ID' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json'

Example Response

 {
  "reportId": "f12ba5df-0673-4917-92ce-4f6c84a3ace8",
  "userId": "...",
  "parameters": {
    "filter": [
      "tags.owner CONTAINS 'shep'",
      "state != 'OFFLINE'"
    ],
    ...
    "details": false
  },
  "state": "SUCCEEDED",
  "requestTime": 1682510562745,
  "startTime": 1682510570860,
  "finishTime": 1316,
  "data": [
    {
      "state": "TERMINATED",
      "data": [
        {
          "agentVersion": "1.0.0-271",
          "data": [
            {
              "componentName": "commons-io",
              "tags.owner": "ashepotko",
              "componentVersion": "2.11.0",
              "count": 26
            },
            {
              "componentName": "crs-tests-jar-with-dependencies.jar",
              "tags.owner": "ashepotko",
              "componentVersion": "UNKNOWN",
              "count": 26
            },
            ...
          ]
        },
        {
          "agentVersion": "1.0.11-568",
          "data": [
            {
              "componentName": "aether-connector-basic",
              "tags.owner": "ashepotko",
              "componentVersion": "1.1.0",
              "count": 11
            },
            ...
          ]
        },
        ...
      ]
    }
  ],
  "totalCount": 44
}

Count values used in the response:

count: The number of VMs which satisfy the provided filter.
totalCount: The number of report elements.