Scope resources at the integration level
Scope resource in or out of your Vanta instance
Scope resources
In order to scope resources at the integration level, we'll need to utilize several endpoints.
Steps:
- GET our list of connected integrations, or a known connected integration
- GET resource kind details for a connected integration
- GET resources for that resource kind
- PATCH a single resource, or multiple resources to set their scope
List Integrations Endpoint
The integrations endpoint can be used to list all the integration ids, the resource kinds associated with that specific integration, as well as the integration's connectionIds
. We'll also need the resourceKind
and integrationId
later on to filter what kind of resources we want to scope.
If you don't know the IntegrationId
of the integration you're attempting to scope, use this endpoint to return a list of connected integrations, along with their resource kinds.
Endpoint:
/integrations
Query Parameters:
pageSize
(<number>
): An integer value that specifies the number of resources to return per page. This parameter controls the size of each page in paginated responses.pageCursor
(<string>
): A string value used to navigate through pages of results. This parameter holds the cursor for the current page, allowing the API to fetch the next set of results.
List Connected Integrations - Code Example
curl --location 'https://api.vanta.com/v1/integrations?pageSize=100&pageCursor=<string>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer your_token'
const myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Authorization", "Bearer your_token");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow"
};
fetch("https://api.vanta.com/v1/integrations?pageSize=100&pageCursor=<string>", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
const axios = require('axios');
let config = {
method: 'get',
maxBodyLength: Infinity,
url: 'https://api.vanta.com/v1/integrations?pageSize=100&pageCursor=<string>',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer your_token'
}
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
import requests
url = "https://api.vanta.com/v1/integrations?pageSize=100&pageCursor=<string>"
payload = {}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer your_token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
List Connected Integrations - Example Response
{
"results": {
"pageInfo": {
"endCursor": "YmFtYm9vX2hy",
"hasNextPage": true,
"hasPreviousPage": false,
"startCursor": "b25lcGFzc3dvcmQ="
},
"data": [
{
"integrationId": "gcp",
"displayName": "Google Cloud Platform",
"resourceKinds": [
"GCPArtifactRegistryRepository",
"BigQueryDataset",
"BigtableInstance",
"GCPCloudIDSEndpoint",
"GCPCloudTasksQueue",
"CloudSQLInstance",
"GCPComputeInstance",
"GCPContainerRepository",
"GCPContainerVulnerabilityV2",
"DatastoreProject",
"FirestoreProject",
"GCPLogBucket",
"GCPLogSink",
"GCPMetric",
"GCPMonitoringPolicy",
"GCPNetwork",
"GCPOrganizationProject",
"GCPRole",
"GCPRoleGrant",
"SpannerInstance",
"GCPStorageBucket",
"GCPSubnet",
"GCPSubscription",
"GCPTopic",
"GCPKubernetesCluster",
"GCPKubernetesNode"
],
"connections": [
{
"connectionId": "66141bbae88e3ea7bc2f0023",
"isDisabled": false,
"connectionErrorMessage": null
},
{
"connectionId": "66141bbae88e3ea7bc2f0024",
"isDisabled": false,
"connectionErrorMessage": null
}
]
}
]
}
]
}
}
Get Integration Endpoint
You can target a specific integration's details if you already know the IntegrationId
rather than returning a list of integrations like the previous example.
Endpoint:
/integrations/:integrationId
Path Variables:
integrationId
: The<string>
id of the connected Integration. This variable is necessary to specify which integration the request is targeting.
Get Connected Integration- Code Example
curl --location 'https://api.vanta.com/v1/integrations/gcp' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer your_token'
const myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Authorization", "Bearer your_token");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow"
};
fetch("https://api.vanta.com/v1/integrations/gcp", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
const axios = require('axios');
let config = {
method: 'get',
maxBodyLength: Infinity,
url: 'https://api.vanta.com/v1/integrations/gcp',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer your_token'
}
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
import requests
url = "https://api.vanta.com/v1/integrations/gcp"
payload = {}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer your_token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
Get Connected Integration - Example Response
{
"integrationId": "gcp",
"displayName": "Google Cloud Platform",
"resourceKinds": [
"GCPArtifactRegistryRepository",
"BigQueryDataset",
"BigtableInstance",
"GCPCloudIDSEndpoint",
"GCPCloudTasksQueue",
"CloudSQLInstance",
"GCPComputeInstance",
"GCPContainerRepository",
"GCPContainerVulnerabilityV2",
"DatastoreProject",
"FirestoreProject",
"GCPLogBucket",
"GCPLogSink",
"GCPMetric",
"GCPMonitoringPolicy",
"GCPNetwork",
"GCPOrganizationProject",
"GCPRole",
"GCPRoleGrant",
"SpannerInstance",
"GCPStorageBucket",
"GCPSubnet",
"GCPSubscription",
"GCPTopic",
"GCPKubernetesCluster",
"GCPKubernetesNode"
],
"connections": [
{
"connectionId": "66141bbae88e3ea7bc2f0023",
"isDisabled": false,
"connectionErrorMessage": null
},
{
"connectionId": "66141bbae88e3ea7bc2f0024",
"isDisabled": false,
"connectionErrorMessage": null
}
]
}
Get Connected Integration - Response Schema
The response contains the following fields for each integration:
-
integrationId
: A unique human-readable identifier for the integration. -
displayName
: The name of the integration as it is displayed, e.g., "Google Cloud Platform". -
resourceKinds
: An array listing the different kinds of resources associated with the integration.
connections
: An array of objects representing the different connections associated with the integration.
connections
: An array of objects representing the different connections associated with the integration.- Each connection object contains:
Get Resource Kind Endpoint
We can use this endpoint to retrieve summary details about a resource kind for a specific integrationId
and connectionId
.
Endpoint:
/integrations/:integrationId/resource-kinds/:resourceKind?connectionId=<string>
Query Parameters:
connectionId
: The<string>
value of the connectionId you can optionally target. This parameter is used to specify which connection's resources you want to retrieve.
Path Variables:
integrationId
: The<string>
id of the connected Integration. This variable is necessary to specify which integration the request is targeting.resourceKind
: The<string>
value of the target resourceKind. This variable is necessary to specify the kind of resource for which details or a list of resources are being requested.
Get Resource Kind - Code Example
curl --location 'https://api.vanta.com/v1/integrations/gcp/resource-kinds/GCPComputeInstance?connectionId=663e78b85360cc947add64bd' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer your_token'
const myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Authorization", "Bearer vat_YOUR_TOKEN_HERE");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow"
};
fetch("https://api.vanta.com/v1/integrations/gcp/resource-kinds/GCPComputeInstance?connectionId=663e78b85360cc947add64bd", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
const axios = require('axios');
let config = {
method: 'get',
maxBodyLength: Infinity,
url: 'https://api.vanta.com/v1/integrations/gcp/resource-kinds/GCPComputeInstance?connectionId=663e78b85360cc947add64bd',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer vat_YOUR_TOKEN_HERE'
}
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
import requests
url = "https://api.vanta.com/v1/integrations/gcp/resource-kinds/GCPComputeInstance?connectionId=663e78b85360cc947add64bd"
payload = {}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer vat_YOUR_TOKEN_HERE'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
Get Resource Kind - Example Response
{
"integrationId": "gcp",
"resourceKind": "GCPComputeInstance",
"isScopable": true,
"numResources": 8,
"numInScope": 8,
"numOwned": 8,
"numWithDescription": 8
}
Get Resource Kind - Response Schema
The response from the Resource Kind endpoint returns the following details on this specific resourceKind
for whichever connectionId
they're associated with:
-
integrationId
: A unique identifier for the integration, in this case, "gcp". -
resourceKind
: The type of resource within the integration, in this case, "GCPComputeInstance". -
isScopable
: A boolean indicating if the resource kind can be scoped (true means it can be scoped). -
numResources
: The total number of resources of this kind. -
numInScope
: The number of resources of this kind that are currently in scope. -
numOwned
: The number of resources of this kind that are owned. -
numWithDescription
: The number of resources of this kind that have a description.
List Resources Endpoint
This endpoint returns a list of resources from a specified resourceKind
and integrationId
. You may also filter the resources returned by connectionId
:<string>
, hasOwner
:<boolean>
, hasDescription
:<boolean>
and isInScope
:<boolean>
. In the example below, we'll be using the connectionId
and isInScope
: true to filter which GCPComputeInstances we'd like to scope out of Vanta.
Endpoint:
/integrations/:integrationId/resource-kinds/:resourceKind/resources?connectionId=<string>&isInScope=<boolean>&pageSize=10
Query Parameters:
connectionId
: The<string>
value of the connectionId you can optionally target. This parameter is used to specify which connection's resources you want to retrieve.isInScope
(Optional): A<boolean>
value to filter resources that are in scope. When set to true, only resources that are considered in scope will be included in the response.pageSize
(Optional): The<integer>
value to specify the number of resources to return per page. This parameter controls the size of each page in paginated responses.pageCursor
(<string>
): A string value used to navigate through pages of results. This parameter holds the cursor for the current page, allowing the API to fetch the next set of results.
Path Variables:
-
integrationId
: The<string>
id of the connected Integration. This variable is necessary to specify which integration the request is targeting. -
resourceKind
: The<string>
value of the target resourceKind. This variable is necessary to specify the kind of resource for which details or a list of resources are being requested.
List Resources - Code Example
curl --location 'https://api.vanta.com/v1/integrations/gcp/resource-kinds/GCPComputeInstance/resources?connectionId=663e78b85360cc947add64bd&isInScope=true&pageSize=10' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer vat_YOUR_TOKEN_HERE'
const myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Authorization", "Bearer vat_YOUR_TOKEN_HERE");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow"
};
fetch("https://api.vanta.com/v1/integrations/gcp/resource-kinds/GCPComputeInstance/resources?connectionId=663e78b85360cc947add64bd&isInScope=true&pageSize=10", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
const axios = require('axios');
let config = {
method: 'get',
maxBodyLength: Infinity,
url: 'https://api.vanta.com/v1/integrations/gcp/resource-kinds/GCPComputeInstance/resources?connectionId=663e78b85360cc947add64bd&isInScope=true&pageSize=10',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer vat_YOUR_TOKEN_HERE'
}
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
import requests
url = "https://api.vanta.com/v1/integrations/gcp/resource-kinds/GCPComputeInstance/resources?connectionId=663e78b85360cc947add64bd&isInScope=true&pageSize=10"
payload = {}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer vat_YOUR_TOKEN_HERE'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
List Resources - Example Response
{
"results": {
"pageInfo": {
"endCursor": "eyJfaWQiOnsiJG9pZCI6IjY2M2U3OGJiNTM2MGNjOTQ3YWRkZDVmMyJ9fQ==",
"hasNextPage": false,
"hasPreviousPage": false,
"startCursor": "eyJfaWQiOnsiJG9pZCI6IjY2M2U3OGJiNTM2MGNjOTQ3YWRkZDVmMyJ9fQ=="
},
"data": [
{
"responseType": "ComputeInstance",
"resourceKind": "GCPComputeInstance",
"resourceId": "663e78bb5360cc947addd5f3",
"connectionId": "663e78b85360cc947add64bd",
"displayName": "vm-backend-service-2",
"owner": "61a66a98538a952a6533f540",
"inScope": true,
"description": "GCP Compute Instance",
"creationDate": "2024-05-10T19:42:51.419Z",
"account": "amalgamated-widgets-demo",
"region": "https://www.googleapis.com/compute/v1/projects/amalgamated-widgets-demo/zones/us-central1-a"
}
]
}
}
List Resources - Response Schema
The response from the List Resources endpoint above contains the following GCPComputeInstance
resourceKind properties:
pageInfo
: Information about pagination.
pageInfo
: Information about pagination.-
endCursor
: The cursor for the end of the current page. -
hasNextPage
: Boolean indicating if there are more pages. -
hasPreviousPage
: Boolean indicating if there are previous pages. -
startCursor
: The cursor for the start of the current page.
data
: An array of resources.
data
: An array of resources.-
responseType
: The type of the resource. -
resourceKind
: The kind of resource. -
resourceId
: The ID of the resource. -
connectionId
: The ID of the connection. -
displayName
: The display name of the resource. -
owner
: The owner of the resource. -
inScope
: Boolean indicating if the resource is in scope. -
description
: The description of the resource. -
creationDate
: The creation date of the resource. -
account
: The account associated with the resource. -
region
: The region of the resource.
Update Resource Endpoint
In the Update Resource endpoint, we'll send the property inScope:false
via the Update Resource request body.
Endpoint:
/integrations/:integrationId/resource-kinds/:resourceKind/resources/:resourceId
Path Variables:
-
integrationId
: The<string>
id of the connected Integration. This variable is necessary to specify which integration the request is targeting. -
resourceKind
: The<string>
value of the target resourceKind. This variable is necessary to specify the kind of resource for which details or a list of resources are being requested. -
resourceId
: The<string>
value of the target resource's resourceId. This variable is necessary to specify the unique identifier of the specific resource being requested.
Request body:
{
"inScope": "<boolean>",
"description": "<string>",
"ownerId": "<string>"
}
Update Resource - Code Example
curl --location --request PATCH 'https://api.vanta.com/v1/integrations/gcp/resource-kinds/GCPComputeInstance/resources/663e78bb5360cc947addd5f3' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer vat_YOUR_TOKEN_HERE' \
--data '{
"inScope": "false"
}'
const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Accept", "application/json");
myHeaders.append("Authorization", "Bearer vat_YOUR_TOKEN_HERE");
const raw = JSON.stringify({
"inScope": "false"
});
const requestOptions = {
method: "PATCH",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://api.vanta.com/v1/integrations/gcp/resource-kinds/GCPComputeInstance/resources/663e78bb5360cc947addd5f3", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
const axios = require('axios');
let data = JSON.stringify({
"inScope": "false"
});
let config = {
method: 'patch',
maxBodyLength: Infinity,
url: 'https://api.vanta.com/v1/integrations/gcp/resource-kinds/GCPComputeInstance/resources/663e78bb5360cc947addd5f3',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer vat_YOUR_TOKEN_HERE'
},
data : data
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
import requests
import json
url = "https://api.vanta.com/v1/integrations/gcp/resource-kinds/GCPComputeInstance/resources/663e78bb5360cc947addd5f3"
payload = json.dumps({
"inScope": "false"
})
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer vat_YOUR_TOKEN_HERE'
}
response = requests.request("PATCH", url, headers=headers, data=payload)
print(response.text)
Update Resource - Example Response
If successful, you should get a 204 in response.
204 No Content
Update Resources Endpoint
If you have multiple resources you're trying to update, use the Update Resources endpoint. Pass the resourceId
of each resource you'd like to update in the resourceIds list.
Endpoint:
/integrations/:integrationId/resource-kinds/:resourceKind/resources/
Path Variables:
integrationId
: The<string>
id of the connected Integration. This variable is necessary to specify which integration the request is targeting.resourceKind
: The<string>
value of the target resourceKind. This variable is necessary to specify the kind of resource for which details or a list of resources are being requested.
Request body:
{
"resourceIds": [
"<string>"
],
"inScope": "<boolean>",
"description": "<string>",
"ownerId": "<string>"
}
Update Resources - Code Example
curl --location --request PATCH 'https://api.vanta.com/v1/integrations/gcp/resource-kinds/GCPComputeInstance/resources' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer vat_YOUR_TOKEN_HERE' \
--data '{
"resourceIds": [
"663e78bb5360cc947addd5f3"
],
"inScope": "false"
}'
const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Accept", "application/json");
myHeaders.append("Authorization", "Bearer vat_YOUR_TOKEN_HERE");
const raw = JSON.stringify({
"resourceIds": [
"663e78bb5360cc947addd5f3"
],
"inScope": "false"
});
const requestOptions = {
method: "PATCH",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://api.vanta.com/v1/integrations/gcp/resource-kinds/GCPComputeInstance/resources", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
const axios = require('axios');
let data = JSON.stringify({
"resourceIds": [
"663e78bb5360cc947addd5f3"
],
"inScope": "false"
});
let config = {
method: 'patch',
maxBodyLength: Infinity,
url: 'https://api.vanta.com/v1/integrations/gcp/resource-kinds/GCPComputeInstance/resources',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer vat_YOUR_TOKEN_HERE'
},
data : data
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
import requests
import json
url = "https://api.vanta.com/v1/integrations/gcp/resource-kinds/GCPComputeInstance/resources"
payload = json.dumps({
"resourceIds": [
"663e78bb5360cc947addd5f3"
],
"inScope": "false"
})
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer vat_YOUR_TOKEN_HERE'
}
response = requests.request("PATCH", url, headers=headers, data=payload)
print(response.text)
Update Resources - Example Response
204 No Content
Updated 4 months ago