Vanta Developer Console
Docs

Scope resources at the integration level

Scope resource in or out of your Vanta instance

Suggest Edits

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.

  • Each connection object contains:
    • connectionId: A unique identifier for the connection.
    • isDisabled: A boolean indicating if the connection is disabled (false means it is enabled).
    • connectionErrorMessage: A message describing any error associated with the connection (null if no errors).

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.

  • 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.

  • 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 5 months ago