Overview

Vanta offers multiple resource types to align with customer requirements, and the recommendation is to always try to leverage these when creating custom integrations for continuous monitoring.

Given the multiple markets and industries served by Vanta, our customers might still have specific needs around the information or data that should be sent to Vanta that might not be classified under one of Vanta's existing base resource types.

In order to support those scenarios, Vanta provides a "Custom Resource" type that will act as a base schema for users to create their own resource schemas. They can then use these custom resources to send any data they want to Vanta, by providing their own schema of properties a specific resource should contain.

🚧

To make use of your Custom Resource in Vanta, you'll need to build a Custom Test. Learn how to build a Custom Test here: Custom Tests

Example

Create a new resource using the “Custom Resource” resource type option. Give the resource a name and click “Create”. Compared to any other base resource type in Vanta, for a Custom resource, you are required to adjust the schema to fit your use case by adding properties under the Custom Properties JSON Type Definition.

📘

Always add Custom Properties when using the Custom Resource Base type. Otherwise, consider using a different Base Resource Type.

🚧

While this is not a mandatory field for any resource type, not adding custom properties for custom resources will result in a simple resource with only the basic custom resource schema containing display name, unique id, and external url.

Custom properties should follow JSON typedef format and be of one of the following types.

• Boolean
  • True or False
• Int32
  • Numeric integer values
• String
  • Text

Define a very basic Server resource, starting as a custom resource and adding the following json typedef into the Custom Properties section:

{
   "properties": {
       "name": {
           "type": "string"
       },
       "active": {
           "type": "boolean"
       },
       "memory": {
           "type":"int32"
       }
   }
}

This Server resource will have 3 custom properties, name of type string, active of type boolean, and memory of type integer.

Once created, grab the Resource ID as we’ll need it in the subsequent requests. These same steps are described in detail in the Resources section.

Next we will learn how to GET Custom Resources Resources. We will see how Vanta returns an empty resource List.

Then we will PUT Custom Resources Resources to Vanta and confirm successful receipt.

Finally, we will LIST User Accounts Resources again, and Vanta will return all the resources we transmitted in the previous step.

List Custom Resources

GET Request

URL

Obtaining all the resources for a Custom Resource based resource id, requires making a GET request to:

https://api.vanta.com/v1/resources/custom_resource/list_all

The base url "api.vanta.com" is the same we used to get our access token, but the rest of the path "/v1/resources/custom_resource/list_all" is resource type specific and therefore in this case defined only to get resources of type User Account.

📘

Any resources that are created using the Base Resource Type of Custom Resource, will use the above endpoint to LIST all the resources from Vanta.

Parameters

In order to identify the exact resources we want to retrieve from the desired application, we will include the resource id as a parameter in the URL as follows:

<https://api.vanta.com/v1/resources/custom_resource/list_all?resourceId={{customResourceId}}>

Postman will replace the variable {{customResourceId}} with its corresponding current value as defined in the environment.

Headers

The last step before executing our request, is to configure the authorization. Vanta requires a Bearer Token to be passed in the header of the request, and the expected value is the one obtained during the Authentication flow.

Body

This request does not require any data in the body.

Summary

GET Response

Response Code

The expected response code for the above request is 200. This means everything has executed correctly. Any other response means there was an issue with the request. Review all the above steps, check the validity of your authorization token and retry your request.

Headers

Response headers can be ignored.

Body

A successful response will consist of an array of resources that follow the schema defined in Vanta for that resources or am empty list if no resources exist.

Summary

No Resources

Vanta does not have any resources for the given resource Id. This is expected if this is the first request we are making on this resource id, and no resources have yet been sent to Vanta via a SYNC request.

Assuming this guide has been followed in the established order, we have not sent any resources to Vanta, so expect to receive this response.

Resources Available

Vanta has one or more resources for the given resource id. This means a successful SYNC request has already been sent to Vanta pushing a set of resources for Vanta to monitor.

Once you have completed the SYNC Custom Resource step, return here and rerun the above GET request to LIST resources and confirm you are receiving all the resources sent before.

Assuming you have return here after syncing your resources, expect to receive this response.

👍

We have successfully listed all the resources from Vanta for a given resource id!

Sync Custom Resources

PUT Request

🚧

Every PUT request to sync resources into Vanta provides a full state of available resources. This means, every resource to be monitored, needs to be sent with every SYNC request, otherwise, when a previously submitted resource is omitted in a subsequent SYNC, Vanta will assume the resource no longer exists.

URL

Sending all the resources for a User Account based resource id, requires making a PUT request to:

https://api.vanta.com/v1/resources/custom_resource/sync_all

The base url "api.vanta.com" is the same we used to get our access token, but the rest of the path "/v1/resources/custom_resource/sync_all" is resource type specific and therefore in this case defined only to get resources of type User Account.

📘

Any resources that are created using the Base Resource Type of Custom Resource, will use the above endpoint to SYNC all the resources to Vanta.

Parameters

This request does not require any parameters to be sent as part of the URL

Headers

Vanta requires a Bearer Token to be passed in the header of the request, and the expected value is the one obtained during the Authentication flow. This is the same authorization process we did to LIST the resources using a GET Request.

Body

This request requires a JSON Object to be sent in the body. This object will contain the resource Id to identify the resources to be sent, and an array of resources.

Each resource in the array, needs to follow the defined schema for that resource id, as configured in the Resources tab in the applications. Reference the Resources section of this guide as a refreshed if needed.

We will continue to use the resource id from the UserAccount resource type we created earlier. Notice the resource id is included in the body of the request, as part of the JSON Object, and not in the URL as a parameter.

Postman will replace the variable {{customResourceId}} with its corresponding current value as defined in the environment.

Summary

PUT Response

Response Code

The expected response code for the above request is 200. This means everything has executed correctly. Any other response means there was an issue with the request. Review all the above steps, check the validity of your authorization token and retry your request.

Headers

Response headers can be ignored.

Body

A successful response will consist of a JSON Object with only one property called success with a value of True. This indicates Vanta has successfully received and process your resources.

Summary

Check your work by making a new GET Request and confirming the GET Response contains all the resources you have just sent.

👍

We have successfully sent all our resources to Vanta for a given resource id.