Inventories
On this page
ToggleAn inventory is a specific list of data that is gathered to provide information about a certain part of the business. The inventory is inspected by an automated test or by a human to determine if one or more controls are satisfied and to analyze the results of the inventory.
Examples of inventories are users, systems, security incidents, devices, servers, databases, logs, etc.
In this guide, we will learn how to retrieve inventories from the TrustCloud API using REST calls.
Here are five points elaborating on the concept of an inventory in the context of business data management:
- Purpose of Inventory: An inventory is compiled to gather comprehensive information about specific aspects of a business. This data serves various functions, such as ensuring compliance with regulatory requirements, optimizing operations, and enhancing decision-making processes. By maintaining an up-to-date inventory, businesses can monitor their assets, identify trends, and address potential issues proactively.
- Inspection Methods: The inventory can be examined through automated tests or manual inspections. Automated tests provide efficient, consistent, and rapid analysis of large datasets, ensuring that specific controls and criteria are met. Manual inspections, on the other hand, allow for a more nuanced and detailed review by human experts, who can identify context-specific issues that automated systems might miss.
- Types of Inventories: Inventories can encompass various elements of a business, such as users, systems, security incidents, devices, servers, databases, and logs. Each type of inventory provides valuable insights into different areas, such as user behaviour, system performance, security breaches, hardware utilization, data storage, and operational activities.
- Control Satisfaction and Analysis: The primary goal of inspecting inventories is to determine if certain controls are satisfied. Controls are policies, procedures, or technical safeguards that ensure the integrity, confidentiality, and availability of business assets. By analysing the inventory data, businesses can verify compliance with these controls, identify areas for improvement, and implement necessary corrective actions.
- Examples and Applications: Examples of inventories include user lists, which help manage access and permissions; system inventories, which track software and hardware assets; security incident logs, which document and analyse security breaches; device inventories, which monitor the deployment and usage of business devices; server inventories, which manage server performance and capacity; database inventories, which ensure data integrity and availability; and log inventories, which provide detailed records of system and user activities for auditing and troubleshooting purposes. Each of these inventories plays a crucial role in maintaining the overall health and security of the business.
Retrieving an API Key
To make requests to the TrustCloud API, an API key is required. To obtain an API key, follow the instructions in the Getting Started Guide to connect to the API.
Setting up the Request
Before we make any requests, we need to set up our HTTP headers. We need to include the API key in the “Authorization” header, and set the “x-trustcloud-api-version” header to 1 to ensure we are using the correct API version.
Here is an example of the headers we need to include in our HTTP request:
const headers = {
'Authorization': '',
'x-trustcloud-api-version': '1'
};
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
HttpGet request = new HttpGet("https://api.trustcloud.ai/inventories");
request.setHeader("Authorization", "");
request.setHeader("x-trustcloud-api-version", "1");
using RestSharp;
using RestSharp.Authenticators;
using System;
using System.Collections.Generic;
string apiKey = "";
string apiVersion = "1";
string baseUrl = "https://api.trustcloud.ai";
import requests
headers = {
'Authorization': '',
'x-trustcloud-api-version': '1'
}
package main
import (
"encoding/json"
"fmt"
"net/http"
)
apiKey := ""
url := "https://api.trustcloud.ai/inventories"
req, err := http.NewRequest("GET", url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Set("Authorization", apiKey)
req.Header.Set("x-trustcloud-api-version", "1")
GET /inventories HTTP/1.1
Host: api.trustcloud.ai
Authorization: Bearer
x-trustcloud-api-version: 1
Retrieving All Inventories
To retrieve a list of all inventories, make a GET request to the /inventories endpoint using the headers set up in Step 2.
import axios from 'axios';
const headers = {
'Authorization': '',
'x-trustcloud-api-version': '1'
};
axios.get('https://api.trustcloud.ai/inventories, { headers })
.then(response => {
console.log(response.data);
})
.catch(error => {
console.log(error);
});
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
HttpGet request = new HttpGet("https://api.trustcloud.ai/inventories");
request.setHeader("Authorization", "");
request.setHeader("x-trustcloud-api-version", "1");
HttpClient client = HttpClients.createDefault();
CloseableHttpResponse response = client.execute(request);
try {
String responseBody = EntityUtils.toString(response.getEntity());
System.out.println(responseBody);
} finally {
response.close();
}
using RestSharp;
using RestSharp.Authenticators;
using System;
using System.Collections.Generic;
string apiKey = "";
string apiVersion = "1";
string baseUrl = "https://api.trustcloud.ai";
var client = new RestClient(baseUrl);
var request = new RestRequest("/inventories", Method.GET);
request.AddHeader("Authorization", apiKey);
request.AddHeader("x-trustcloud-api-version", apiVersion);
IRestResponse response = client.Execute(request);
if (response.IsSuccessful)
{
Console.WriteLine(response.Content);
}
else
{
Console.WriteLine("Error: " + response.Content);
}
import requests
headers = {
'Authorization': '',
'x-trustcloud-api-version': '1'
}
response = requests.get('https://api.trustcloud.ai/inventories, headers=headers)
if response.status_code == 200:
inventory = response.json()
print(inventory)
else:
print('Error retrieving Inventories:', response.text)
package main
import (
"encoding/json"
"fmt"
"net/http"
)
apiKey := ""
url := "https://api.trustcloud.ai/inventories"
req, err := http.NewRequest("GET", url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Set("Authorization", apiKey)
req.Header.Set("x-trustcloud-api-version", "1")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer resp.Body.Close()
var data []interface{}
err = json.NewDecoder(resp.Body).Decode(&data)
if err != nil {
fmt.Println(err)
return
}
fmt.Printf("%+v\n", data)
GET /inventories HTTP/1.1
Host: api.trustcloud.ai
Authorization: Bearer
x-trustcloud-api-version: 1
Here is an example of the response we might receive:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1234
[
{
"id":"e98b101d-bd44-4261-b90d-76dc35bad38c",
"inventoryId":"fa9092f7-f9e9-4211-8077-3fc86c104efa",
"name":"Access",
"properties":{
"0":{
"displayList":true,
"propertyName":"Name"
},
"1":{
"displayList":true,
"propertyName":"Email"
},
"2":{
"displayList":true,
"propertyName":"Role"
},
"3":{
"displayList":true,
"propertyName":"2FA Enabled?"
},
"4":{
"displayList":true,
"propertyName":"SSO Mode"
}
},
"_metaData":{
"createdBy":"0a32527e-d6d9-44b2-8771-4b2d5d3e7445",
"createdDate":"2023-02-13 05:41:57.635+00",
"lastModifiedBy":"0a32527e-d6d9-44b2-8771-4b2d5d3e7445",
"lastModifiedDate":"2023-07-26 13:12:18.605+00"
},
"resources":[
{
"id":"6d4255da-fefb-4ac6-8287-5f984e1b1690",
"systemId":"b6a9b9bb-3843-4d0b-96f5-5c07e4ca9eb5",
"propertyValues":{
"0":{
"Name":"Project Collection Build Service (Kintent-Trust-Cloud)",
"Role":"user",
"Email":"",
"SSO Mode":"",
"2FA Enabled":""
},
"1":{
"Name":"Test Project Build Service (Kintent-Trust-Cloud)",
"Role":"user",
"Email":"",
"SSO Mode":"",
"2FA Enabled":""
},
"2":{
"Name":"Sloan Ellwood",
"Role":"user",
"Email":Sloane_Ellwood7485@avn7d.services",
"SSO Mode":"",
"2FA Enabled":""
},
"3":{
"Name":Build Service",
"Role":"user",
"Email":"",
"SSO Mode":"",
"2FA Enabled":""
},
},
"_metaData":{
"createdBy":"24490f7f-07a5-4d71-bd5d-6cb08266a09b",
"createdDate":"2022-07-08 23:00:08.041695+00",
"lastModifiedBy":"24490f7f-07a5-4d71-bd5d-6cb08266a09b",
"lastModifiedDate":"2022-07-08 23:00:08.041695+00"
}
}
]
},...
]
Retrieving a Single Inventory
To retrieve a single inventory, include the inventory ID in the URL by appending the ID to the /inventories endpoint. In this example, we will retrieve the inventory with ID
e98b101d-bd44-4261-b90d-76dc35bad38c:
import axios from 'axios';
const headers = {
'Authorization': '',
'x-trustcloud-api-version': '1'
};
const id = 'e98b101d-bd44-4261-b90d-76dc35bad38c'; // Replace with the ID of the inventory you want to retrieve
axios.get(`https://api.trustcloud.ai/inventories/${id}`, { headers })
.then(response => {
console.log(response.data);
})
.catch(error => {
console.log(error);
});
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
HttpGet request = new HttpGet("https://api.trustcloud.ai/inventories/e98b101d-bd44-4261-b90d-76dc35bad38c");
request.setHeader("Authorization", "");
request.setHeader("x-trustcloud-api-version", "1");
HttpClient client = HttpClients.createDefault();
CloseableHttpResponse response = client.execute(request);
try {
String responseBody = EntityUtils.toString(response.getEntity());
System.out.println(responseBody);
} finally {
response.close();
}
using RestSharp;
using RestSharp.Authenticators;
using System;
using System.Collections.Generic;
string apiKey = "";
string apiVersion = "1";
string baseUrl = "https://api.trustcloud.ai";
var client = new RestClient(baseUrl);
var request = new RestRequest("/inventories/{id}", Method.GET);
request.AddHeader("Authorization", apiKey);
request.AddHeader("x-trustcloud-api-version", apiVersion);
request.AddUrlSegment("id", "e98b101d-bd44-4261-b90d-76dc35bad38c");
IRestResponse response = client.Execute(request);
if (response.IsSuccessful)
{
Console.WriteLine(response.Content);
}
else
{
Console.WriteLine("Error: " + response.Content);
}
import requests
headers = {
'Authorization': '',
'x-trustcloud-api-version': '1'
}
response = requests.get('https://api.trustcloud.ai/inventories/e98b101d-bd44-4261-b90d-76dc35bad38c', headers=headers)
if response.status_code == 200:
inventory = response.json()
print(inventory)
else:
print('Error retrieving System:', response.text)
package main
import (
"encoding/json"
"fmt"
"net/http"
)
apiKey := ""
url := "https://api.trustcloud.ai/inventories/e98b101d-bd44-4261-b90d-76dc35bad38c"
req, err := http.NewRequest("GET", url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Set("Authorization", apiKey)
req.Header.Set("x-trustcloud-api-version", "1")
req, err := http.NewRequest("GET", url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Set("Authorization", apiKey)
req.Header.Set("x-trustcloud-api-version", "1")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer resp.Body.Close()
var data map[string]interface{}
err = json.NewDecoder(resp.Body).Decode(&data)
if err != nil {
fmt.Println(err)
return
}
fmt.Printf("%+v\n", data)
GET /inventories/e98b101d-bd44-4261-b90d-76dc35bad38c HTTP/1.1
Host: API.trustcloud.ai
Authorization:
x-trustcloud-api-version: 1
Here is an example of the response we might receive:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 234
{
"id":"e98b101d-bd44-4261-b90d-76dc35bad38c",
"inventoryId":"fa9092f7-f9e9-4211-8077-3fc86c104efa",
"name":"Access",
"properties":{
"0":{
"displayList":true,
"propertyName":"Name"
},
"1":{
"displayList":true,
"propertyName":"Email"
},
"2":{
"displayList":true,
"propertyName":"Role"
},
"3":{
"displayList":true,
"propertyName":"2FA Enabled?"
},
"4":{
"displayList":true,
"propertyName":"SSO Mode"
}
},
"_metaData":{
"createdBy":"0a32527e-d6d9-44b2-8771-4b2d5d3e7445",
"createdDate":"2023-02-13 05:41:57.635+00",
"lastModifiedBy":"0a32527e-d6d9-44b2-8771-4b2d5d3e7445",
"lastModifiedDate":"2023-07-26 13:12:18.605+00"
},
"resources":[
{
"id":"6d4255da-fefb-4ac6-8287-5f984e1b1690",
"systemId":"b6a9b9bb-3843-4d0b-96f5-5c07e4ca9eb5",
"propertyValues":{
"0":{
"Name":"Project Collection Build Service (Kintent-Trust-Cloud)",
"Role":"user",
"Email":"",
"SSO Mode":"",
"2FA Enabled":""
},
"1":{
"Name":"Test Project Build Service (Kintent-Trust-Cloud)",
"Role":"user",
"Email":"",
"SSO Mode":"",
"2FA Enabled":""
},
"2":{
"Name":"Sloan Ellwood",
"Role":"user",
"Email":Sloane_Ellwood7485@avn7d.services",
"SSO Mode":"",
"2FA Enabled":""
},
"3":{
"Name":Build Service",
"Role":"user",
"Email":"",
"SSO Mode":"",
"2FA Enabled":""
},
},
"_metaData":{
"createdBy":"24490f7f-07a5-4d71-bd5d-6cb08266a09b",
"createdDate":"2022-07-08 23:00:08.041695+00",
"lastModifiedBy":"24490f7f-07a5-4d71-bd5d-6cb08266a09b",
"lastModifiedDate":"2022-07-08 23:00:08.041695+00"
}
}
]
}
Paging
If there are a large number of inventories in a response, it is recommended to use paging to retrieve them in batches. To do this, we can use the limit and page query parameters.
The limit parameter specifies the number of records to retrieve in each page. The default value is 100, but we can set it to any value up to 1000.
The page parameter specifies which page to retrieve. The first page is page 1.
For example, to retrieve the first 10 inventories:
import axios from 'axios';
const headers = {
'Authorization': '',
'x-trustcloud-api-version': '1'
};
const limit = 10; // The number of Inventory to retrieve per page
const page = 1; // The page number to retrieve (starts at 1)
axios.get('https://api.trustcloud.ai/inventories, {
headers,
params: {
limit,
page,
}
})
.then(response => {
console.log(response.data);
console.log(response.headers.link); // log link header
})
.catch(error => {
console.log(error);
});
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
HttpGet request = new HttpGet("https://api.trustcloud.ai/inventories?limit=10&page=1");
request.setHeader("Authorization", "");
request.setHeader("x-trustcloud-api-version", "1");
HttpClient client = HttpClients.createDefault();
CloseableHttpResponse response = client.execute(request);
try {
String responseBody = EntityUtils.toString(response.getEntity());
System.out.println(responseBody);
} finally {
response.close();
}
using System;
using System.Collections.Generic;
string apiKey = "";
string apiVersion = "1";
string baseUrl = "https://api.trustcloud.ai";
var client = new RestClient(baseUrl);
var request = new RestRequest("/inventories", Method.GET);
request.AddHeader("Authorization", apiKey);
request.AddHeader("x-trustcloud-api-version", apiVersion);
request.AddParameter("limit", 50);
request.AddParameter("page", 1);
IRestResponse response = client.Execute(request);
if (response.IsSuccessful)
{
Console.WriteLine(response.Content);
}
else
{
Console.WriteLine("Error: " + response.Content);
}
import requests
headers = {
'Authorization': '',
'x-trustcloud-api-version': '1'
}
response = requests.get('https://api.trustcloud.ai/inventories?limit=10&page=1', headers=headers', headers=headers)
if response.status_code == 200:
inventory = response.json()
print(inventory)
else:
print('Error retrieving Inventories:', response.text)
package main
import (
"encoding/json"
"fmt"
"net/http"
)
apiKey := ""
url := "https://api.trustcloud.ai/inventories?page=1&limit=10"
req, err := http.NewRequest("GET", url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Set("Authorization", apiKey)
req.Header.Set("x-trustcloud-api-version", "1")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer resp.Body.Close()
var data []interface{}
err = json.NewDecoder(resp.Body).Decode(&data)
if err != nil {
fmt.Println(err)
return
}
fmt.Printf("%+v\n", data)
GET /inventories?limit=10&page=1 HTTP/1.1
Host: API.trustcloud.ai
Authorization:
x-trustcloud-api-version: 1
To retrieve the next set of inventories, you can obtain the next URL from the link response header, or manually increment the page number. If link is null, that means there are no more pages.
import axios from 'axios';
const headers = {
'Authorization': '',
'x-trustcloud-api-version': '1'
};
const limit = 10; // The number of Inventories to retrieve per page
const page = 1; // The page number to retrieve (starts at 1)
axios.get('https://api.trustcloud.ai/inventories, {
headers,
params: {
limit,
page,
}
})
.then(response => {
console.log(response.data);
console.log(response.headers.link); // log link header
})
.catch(error => {
console.log(error);
});
String linkHeader = response.getFirstHeader("link").getValue();
String nextPageUrl = linkHeader.split(";")[0].replace("<", "").replace(">", "");
HttpGet nextPageRequest = new HttpGet(nextPageUrl);
nextPageRequest.setHeader("Authorization", "");
nextPageRequest.setHeader("x-trustcloud-api-version", "1");
using System;
using System.Collections.Generic;
string apiKey = "";
string apiVersion = "1";
string baseUrl = "https://api.trustcloud.ai";
var client = new RestClient(baseUrl);
var request = new RestRequest("/inventories", Method.GET);
request.AddHeader("Authorization", apiKey);
request.AddHeader("x-trustcloud-api-version", apiVersion);
request.AddParameter("limit", 50);
request.AddParameter("page", 1);
IRestResponse response = client.Execute(request);
if (response.IsSuccessful)
{
Console.WriteLine(response.Content);
// retrieve next page
var nextPageUrl = response.Headers.FirstOrDefault(x => x.Name == "Link")?.Value?.Split(';')[0]?.Trim('<', '>');
if (!string.IsNullOrEmpty(nextPageUrl))
{
var nextPageRequest = new RestRequest(nextPageUrl, Method.GET);
nextPageRequest.AddHeader("Authorization", apiKey);
nextPageRequest.AddHeader("x-trustcloud-api-version", apiVersion);
IRestResponse nextPageResponse = client.Execute(nextPageRequest);
if (nextPageResponse.IsSuccessful)
{
Console.WriteLine(nextPageResponse.Content);
}
else
{
Console.WriteLine("Error retrieving next page: " + nextPageResponse.Content);
import requests
import re
headers = {
'Authorization': '',
'x-trustcloud-api-version': '1'
}
response = requests.get('https://api.trustcloud.ai/inventories?limit=10&page=1', headers=headers)
if response.status_code == 200:
inventory = response.json()
print(inventory)
link_header = response.headers.get('link')
if link_header:
nextPage = re.search('<(.+)>', link_header)
else:
print('Error retrieving Inventories:', response.text)
package main
import (
"fmt"
"io/ioutil"
"log"
"net/http"
"strings"
)
func main() {
apiKey := ""
url := "https://api.trustcloud.ai/inventories"
// Create a new HTTP client
client := &http.Client{}
// Create a new HTTP request
req, err := http.NewRequest("GET", url, nil)
if err != nil {
log.Fatal(err)
}
// Add the API key and version headers
req.Header.Set("Authorization", apiKey)
req.Header.Set("x-trustcloud-api-version", "1")
// Add the page and limit parameters
q := req.URL.Query()
q.Add("page", "1")
q.Add("limit", "10")
req.URL.RawQuery = q.Encode()
// Make the API call
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
// Check the response status code
if resp.StatusCode != http.StatusOK {
log.Fatal(resp.Status)
}
// Parse the link header to get the URL for the next page
linkHeader := resp.Header.Get("Link")
nextPageURL := ""
if linkHeader != "" {
links := strings.Split(linkHeader, ",")
for _, link := range links {
if strings.Contains(link, "rel=\"next\"") {
parts := strings.Split(link, ";")
if len(parts) > 0 {
nextPageURL = strings.Trim(parts[0], "<>")
}
}
}
}
// Read the response body
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
log.Fatal(err)
}
// Print the response body
fmt.Println(string(body))
// Make the API call for the next page if it exists
if nextPageURL != "" {
// Create a new HTTP request for the next page
nextPageReq, err := http.NewRequest("GET", nextPageURL, nil)
if err != nil {
log.Fatal(err)
}
// Add the API key and version headers to the next page request
nextPageReq.Header.Set("Authorization", apiKey)
nextPageReq.Header.Set("x-trustcloud-api-version", "1")
// Make the next page API call
nextPageResp, err := client.Do(nextPageReq)
if err != nil {
log.Fatal(err)
}
defer nextPageResp.Body.Close()
// Check the response status code for the next page
if nextPageResp.StatusCode != http.StatusOK {
log.Fatal(nextPageResp.Status)
}
// Read the response body for the next page
nextPageBody, err := ioutil.ReadAll(nextPageResp.Body)
if err != nil {
log.Fatal(err)
}
// Print the response body for the next page
fmt.Println(string(nextPageBody))
}
}
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 234
link: ; rel="next"
GET /vendors?pag2&limit=10 HTTP/1.1
Host: API.trustcloud.ai
Authorization:
x-trustcloud-api-version: 1
API Reference
In conclusion, managing inventories through TrustCloud’s API involves a systematic approach to gathering, inspecting, and analyzing critical business data. The process begins with obtaining an API key, setting up the necessary HTTP headers, and making appropriate REST calls to retrieve either all inventories or a specific inventory by its ID. For businesses dealing with extensive inventories, leveraging paging parameters ensures efficient data retrieval. By following the detailed steps outlined in this guide, users can effectively interact with the TrustCloud API, thereby streamlining their inventory management and enhancing their overall compliance efforts. This guide serves as a comprehensive resource for professionals seeking to optimize their inventory processes using TrustCloud.