Google Vault
This Integration is part of the Google Vault Pack.#
Use the Google Vault integration to support your archiving and eDiscovery needs for G Suite.
Playbooks
- Google Vault Generic Playbook
- Google Vault - Search Mail
- Google Vault - Search Drive
- Google Vault - Search Groups
- Google Vault - Display Results
Use cases
- Create Google Vault matters, holds, and exports.
- Preserve-in-place (Add a user to a hold)
- Search for information within emails, drives, groups and Hangouts chats.
Configure Google Vault on Cortex XSOAR
- Navigate to Settings > Integrations > Servers & Services .
- Search for Google Vault.
-
Click
Add instance
to create and configure a new integration instance.
- Name : a textual name for the integration instance.
- Username
- Authentication file contents : Service Account Authentication json contents.
- Trust any certificate (not secure)
- Use system proxy settings
- Click Test to validate the URLs, token, and connection.
Create Authentication File Contents
You need to create an authentication file to authenticate Google Vault.
-
Set up a new project in the Google APIs Console and activate Vault API service.
https://code.google.com/apis/console
- Set up authentication and authorization. For more information, see the Google documentation .
-
Select
ENABLE APIS AND SERVICES
>
G Suite Vault API
>
ENABLE
.
-
On the right side, click
CREATE CREDENTIALS
.
Credentials are required to access and use the API. - Select Which API are you using? > G Suite Vault API .
- From the 2nd drop-down list, under "Where will you be calling the API from?", choose "Other UI (e.g. Windows, CLI tool)
- Under "What data will you be accessing?", choose "Application Data".
-
Click "What credentials do I need?"
- Click Create credentials > Service account key .
-
Under Service account, click
Select
>
New service account
.
Make sure you select JSON for the key type. -
Make the account role "Owner" and click "Continue"
- Download the JSON file that is given to you. Open it using Notepad and copy its contents.
-
Under "Username" and "Password" in the integration settings panel, enter your Google username and password.
Place the contents of the JSON file the way they are, under the "Authentication file contents" field. -
Delegate domain-wide authority to the service account, following these instructions:
Go to your G Suite domain’s Admin console: http://admin.google.com/
Select Security from the list of controls. If you don't see Security listed, select More controls from the gray bar at the bottom of the page, then select Security from the list of controls. If you can't see the controls, make sure you're signed in as an administrator for the domain.
Select Show more and then Advanced settings from the list of options.
Select Manage API client access in the Authentication section.
In the Client Name field enter the service account's Client ID. You can find your service account's client ID in the Service accounts page: https://console.developers.google.com/iam-admin/serviceaccounts
Click on the service account name. You may need to click "Edit" and enable the delegation on that screen, and click save.
In the One or More API Scopes field, enter the list of scopes that your application should be granted access to. -
Enter your client ID and these scopes.
- eDiscovery: https://www.googleapis.com/auth/ediscovery
- Dev Storage Full Control: https://www.googleapis.com/auth/devstorage.full_control
-
Click
Authorize
.
Commands
You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.
- Create a Google Vault export: gvault-create-export-mail
- Create a matter: gvault-create-matter
- Create a Google Vault export for Drives: gvault-create-export-drive
- Update a matter state: gvault-matter-update-state
- Create a Google Vault export for Groups: gvault-create-export-groups
- Create a hold for a matter: gvault-create-hold
- Add a Held Account to a hold: gvault-add-heldAccount
- Remove a Held Account from a hold: gvault-remove-heldAccount
- Delete a hold: gvault-delete-hold
- Get a list of matters: gvault-list-matters
- Search for matters: gvault-get-matter
- List all holds for a matter: gvault-list-holds
- Get the status of exports: gvault-export-status
- Download an export: gvault-download-results
- Get the status of a Drives export: gvault-get-drive-results
- Get the results of a Mail export: gvault-get-mail-results
- Get the results of a Groups export: gvault-get-groups-results
1. Create a Google Vault export
Creates a Google Vault export in order to perform search actions on emails.
Base Command
gvault-create-export-mail
Input
| Argument Name | Description | Required |
|---|---|---|
| matterID | The matter ID | Require |
| exportName | Export Name | Required |
| dataScope | Search scope, default is "All Data"; "All Data", "Held Data", "Unprocessed Data" | Optional |
| searchMethod | Search method, default is "All Accounts"; "All Accounts", "Specific Accounts" (requires the "email" argument), "Organizational Unit" (requires the "ou" argument) | Optional |
| emails | CSV list of emails to search in. Use this argument if the "searchMethod" argument is set to "Specific Accounts" | Optional |
| ou | The organizational unit. Only use this argument if the "searchMethod" argument is set to "Organizational Unit" | Optional |
| includeDrafts | Whether to include drafts in the search, default is "true"; "true" or "false" | Optional |
| timeFrame | Search time frame, e.g., "1 min ago","2 weeks ago","3 months ago" | Optional |
| startTime | Search start time in UTC (2018-10-16T12:59:02.584000Z) | Optional |
| endTime | Search end time in UTC (2018-10-16T12:59:02.584000Z) | Optional |
| terms | Apply specific terms to the search, e.g., (subject:example) | Optional |
| exportPST | Export in PST format, default is "true"; "true" or "false" | Optional |
| exportMBOX | Export in MBOX format, default is "false"; "true" or "false" | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| GoogleVault.Matter.Export.MatterID | string | Matter ID |
| GoogleVault.Matter.Export.ExportID | string | Export ID |
| GoogleVault.Matter.Export.Name | string | Export's name |
| GoogleVault.Matter.Export.CreateTime | string | Export's creation time |
Command Example
!gvault-create-export-mail matterID="0bebe0ec-ee41-4955-96b3-20d9408409c8" exportName="mail_test_export412Z85Fs5q" dataScope="All Data" searchMethod="Specific Accounts(requires emails argument)" emails="test@gmail.com" includeDrafts="true" timeFrame="7 days ago" terms="subject:test" exportPST="true"
Context Example
Human Readable Output
2. Create a matter
Creates a new matter with the specified name and description. The initial state is open, and the owner is the method caller. First, checks if a matter with the same name already exists.
Base Command
gvault-create-matter
Input
| Argument Name | Description | Required |
|---|---|---|
| name | A name for the new matter | Required |
| description | A description for the matter | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| GoogleVault.Matter.Name | string | Matter name |
| GoogleVault.Matter.ID | string | Matter ID |
| GoogleVault.Matter.State | string | Matter's state |
Command Example
!gvault-create-matter name=test description=test
Context Example
Human Readable Output
3. Create a Google Vault export for Drives
Creates a Google Vault export in order to perform search actions on drives.
Base Command
gvault-create-export-drive
Input
| Argument Name | Description | Required |
|---|---|---|
| matterID | Matter ID | Required |
| exportName | Export Name | Required |
| dataScope | Search scope, default is "All Data"; "All Data", "Held Data", "Unprocessed Data" | Optional |
| searchMethod | Search method, default is "Specific Accounts"; "Specific Accounts" (requires the "email" argument), "Organizational Unit" (requires the "ou" argument), "Team Drive" | Optional |
| emails | CSV list of emails to search in. Use this argument if the "searchMethod" argument is set to "Specific Accounts" | Optional |
| ou | The organizational unit. Only use this argument if the "searchMethod" argument is set to "Organizational Unit" | Optional |
| teamDrive | If the searchMethod is set to Team Drives | Optional |
| includeTeamDrives | Whether to include team drives, default is "true"; "true" or "false" | Optional |
| timeFrame | Search time frame | Optional |
| startTime | Search start time in UTC (2018-10-16T12:59:02.584000Z) | Optional |
| endTime | Search end time in UTC (2018-10-16T12:59:02.584000Z) | Optional |
| terms | Apply specific terms to the search | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| GoogleVault.Matter.Export.MatterID | string | Matter ID |
| GoogleVault.Matter.Export.ExportID | string | Export ID |
| GoogleVault.Matter.Export.Name | string | Export's name |
| GoogleVault.Matter.Export.CreateTime | string | Export's creation time |
Command Example
!gvault-create-export-drive matterID="0124e0ec-ee41-4955-96b3-20d9408409c8" exportName="drive_test_export" dataScope="All Data" searchMethod="Team Drive" emails="test@google.com,test2@google.com" teamDrive="sdDbMMsaWJNw2Uk9PVA,WCSM4L2G2JU4NUk9PVA" includeTeamDrives="false" terms="subject:quarters income"
Context Example
Human Readable Output
4. Update a matter state
Updates a matter's state.
Base Command
gvault-matter-update-state
Input
| Argument Name | Description | Required |
|---|---|---|
| matterID | The matter ID | Required |
| state | New matter state; "CLOSE", "DELETE", "REOPEN", "UNDELETE" | Required |
Context Output
| Path | Type | Description |
|---|---|---|
| GoogleVault.Matter.Name | string | Matter name |
| GoogleVault.Matter.MatterID | string | Matter ID |
| GoogleVault.Matter.State | string | Matter's state |
5. Create a Google Vault export for Groups
Creates a Google Vault Export in order to perform search actions on Google groups.
Base Command
gvault-create-export-groups
Input
| Argument Name | Description | Required |
|---|---|---|
| matterID | The matter ID | Required |
| exportName | Export name | Required |
| dataScope | Search scope, default is "All Data"; "All Data", "Held Data", "Unprocessed Data" | Optional |
| groups | CSV list of groups, maximum of 50 groups | Required |
| timeFrame | Search time frame | Optional |
| startTime | Search start time in UTC (2018-10-16T12:59:02.584000Z) | Optional |
| endTime | Search end time in UTC (2018-10-16T12:59:02.584000Z) | Optional |
| terms | Apply specific terms to the search | Optional |
| exportPST | Export in PST format, default is "true"; "true" or "false" | Optional |
| exportMBOX | Export in MBOX format, default is "false"; "true" or "false" | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| GoogleVault.Matter.Export.MatterID | string | Matter ID |
| GoogleVault.Matter.Export.ExportID | string | Export ID |
| GoogleVault.Matter.Export.Name | string | Export's name |
| GoogleVault.Matter.Export.CreateTime | string | Export's creation time |
Command Example
!gvault-create-export-groups matterID="0b8d30ec-ee41-4955-96b3-20d9408409c8" exportName="groups_test_export1" dataScope="All Data" groups="group@dgmail.com,test@gmail.com" exportPST="true"
Context Example
Human Readable Output
6. Create a hold for a matter
Creates a hold in the given matter. Holds are used to preserve data in the organization.
Base Command
gvault-create-hold
Input
| Argument Name | Description | Required |
|---|---|---|
| matterID | The matter ID | Required |
| holdName | Name of the new hold | Required |
| corpus | New hold's corpus type; "Mail", "Drive", "Groups" | Required |
| accountID | CSV list of accounts/group IDs to place in the hold, requires at least one account/group ID | Required |
| timeFrame | Search timeframe | Optional |
| startTime | Search start time in UTC (1994-11-05T13:15:30Z ) | Optional |
| endTime | Search end time in UTC (1994-11-05T13:15:30Z ) | Optional |
| terms | The terms that must be matched for a message to be covered by this hold. | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| GoogleVaulty.Hold.Name | string | Hold name |
| GoogleVault.Hold.ID | string | Hold ID |
| GoogleVault.Hold.Account.ID | string | Held account ID |
Command Example
!gvault-create-hold matterID=ffcd6bfc-2530-413e-9d54-2d0801f91765 accountID=116238185592796178843 corpus=Mail holdName=test
Context Example
Human Readable Output
7. Add a Held Account to a hold
Adds a Held Account to a hold. This structure is immutable.
Base Command
gvault-add-heldAccount
Input
| Argument Name | Description | Required |
|---|---|---|
| matterID | The matter ID | Required |
| holdID | The hold ID | Required |
| accountID | The account/group ID to place in hold | Required |
Context Output
| Path | Type | Description |
|---|---|---|
| GoogleVault.Matter.Hold.Account.ID | unknown | The held account ID |
Command Example
!gvault-add-heldAccount matterID="6e067f34-7fac-4ab2-bd9f-eede4f32dd32" holdID="41l9c2w2oqtmjc" accountID="101966995162112532972"
Context Example
Human Readable Output
8. Remove a Held Account from a hold
Removes a Held Account from a hold.
Base Command
gvault-remove-heldAccount
Input
| Argument Name | Description | Required |
|---|---|---|
| matterID | The matter ID | Required |
| holdID | The hold ID | Required |
| accountID | Account ID to remove from hold | Required |
Context Output
There is no context output for this command.
Command Example
!gvault-remove-heldAccount matterID=6e067f1d-7fac-4ab2-bd9f-eede4f32dd32 holdID=41l9c2w2oqtmjc accountID=101966936162112532972
Context Example
Human Readable Output
9. Delete a hold
Removes a hold by ID. This will release any Held Accounts on this Hold.
Base Command
gvault-delete-hold
Input
| Argument Name | Description | Required |
|---|---|---|
| matterID | The matter ID | Required |
| holdID | The hold ID | Required |
Context Output
There is no context output for this command.
Command Example
!gvault-delete-hold matterID=6e067f1d-7fac-4ab2-bd9f-eede4f32dd32 holdID=41l9c2w2oqtmjc
Human Readable Output
10. Get a list of matters
Lists matters the user has access to.
Base Command
gvault-list-matters
Input
| Argument Name | Description | Required |
|---|---|---|
| state | If set, list only matters with that specific state, default is "ALL"; "ALL", "OPEN", "CLOSED", "DELETED" | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| GoogleVault.Matter.Name | string | The matter name |
| GoogleVault.Matter.MatterID | string | Matter ID |
| GoogleVault.Matter.State | string | Matter's state |
Command Example
!gvault-list-matters
Context Example
Human Readable Output
11. Search for matters
Search for a matter by name or by ID.
Base Command
gvault-get-matter
Input
| Argument Name | Description | Required |
|---|---|---|
| matterName | Search by matter name (multiple matters with the same name can exist) | Optional |
| matterID | Search by matter ID | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| GoogleVault.Matter.Name | unknown | Matter name |
| GoogleVault.Matter.ID | unknown | Matter ID |
| GoogleVault.Matter.State | unknown | Matter's state |
Command Example
!gvault-get-matter matterID=04e6d4b2-b67c-4679-adee-ae273b5ef984
Context Example
Human Readable Output
12. List all holds for a matter
Lists all holds for a specified matter.
Base Command
gvault-list-holds
Input
| Argument Name | Description | Required |
|---|---|---|
| matterID | Matter ID | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| GoogleVault.Matter.ID | string | Matter ID |
| GoogleVault.Matter.Hold.name | string | Hold name |
| GoogleVault.Matter.Hold.ID | string | Hold ID |
Command Example
!gvault-list-holds matterID=0bebe0ec-ee41-4955-96b3-20d9408409c8
Context Example
Human Readable Output
13. Get the status of exports
Gets the status of one or more specified exports.
Base Command
gvault-export-status
Input
| Argument Name | Description | Required |
|---|---|---|
| matterId | The matter ID | Optional |
| exportIDS | CSV list of one or more export IDs | Optional |
| queryIDS | MatterID and ExportID concatenation separated by '#' (used only for playbook) such: <Matter_ID># | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| GoogleVault.Matter.Export.MatterID | string | Matter ID |
| GoogleVault.Matter.Export.ExportID | string | Export ID |
| GoogleVault.Matter.Export.Name | string | Export name |
| GoogleVault.Matter.Export.Status | string | Export status |
| GoogleVault.Matter.Export.BucketName | string | Bucket holder name for this export |
| GoogleVault.Matter.Export.DownloadID | string | ID to be used by the "download-export" command |
| GoogleVault.Matter.Export.ViewID | string | ID to be used by the "get-X-results" command (X=drive/mail/groups) |
Command Example
!gvault-export-status exportIDS=exportly-7b8ae442-bee7-4bc9-89fa-a65c6c24d50c matterId=0bebe0ec-ee41-4955-96b3-20d9408409c8
Context Example
Human Readable Output
14. Download an export
Downloads an export by bucket name and download ID.
Base Command
gvault-download-results
Input
| Argument Name | Description | Required |
|---|---|---|
| bucketName | Name of the bucket that holds the export | Required |
| downloadID | The export download ID | Required |
Context Output
There is no context output for this command.
Command Example
!gvault-download-results bucketName=85d7cacf-5d93-44e5-8d37-4ba6da342d02 downloadID=0bebe0ec-ee41-4955-96b3-20d9408409c8/exportly-7b8ae442-bee7-4bc9-89fa-a65c6c24d50c/drive_test_exportcK29253Af6_0.zip
Human Readable Output
15. Get the results of a Drive export
Get the results of a specified drive export.
Base Command
gvault-get-drive-results
Input
| Argument Name | Description | Required |
|---|---|---|
| bucketName | Name of the bucket that holds the export | Required |
| viewID | The export view ID | Required |
| maxResult | Maximum number of results to return (a high threshold can slow down your browser), default is "30" | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| GoogleVault.Matter.Export.Results.Title | string | Title of the file |
| GoogleVault.Matter.Export.Results.Author | string | Author of the file |
| GoogleVault.Matter.Export.Results.Others | string | Other users related to the file |
| GoogleVault.Matter.Export.Results.Viewers | string | Viewers of the file |
| GoogleVault.Matter.Export.Results.DateModified | string | The date the file was last modified |
| GoogleVault.Matter.Export.Results.DateCreated | string | The date the file was created |
| GoogleVault.Matter.Export.Results.DocType | string | File type (extension) |
| GoogleVault.Matter.Export.Results.MD5 | string | The MD5 of the file (SHA-1) |
Command Example
!gvault-get-drive-results bucketName="85d7cacf-5d93-44e5-8d37-4ba6da342d02" viewID=0bebe0ec-ee41-4955-96b3-20d9408409c8/exportly-ce3e380b-88dd-4057-b8e9-3a53e6f24e6a/drive_test_export412Z85Fs5q-metadata.xml
Context Example
Human Readable Output
16. Get the results of a Mail export
Get the results of a specified Mail export.
Base Command
gvault-get-mail-results
Input
| Argument Name | Description | Required |
|---|---|---|
| bucketName | Name of the bucket that holds the export | Required |
| viewID | The export view ID | Required |
| maxResult | Maximum number of results to return (a high threshold can slow down your browser), default is "30" | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| GoogleVault.Matter.Export.Results.CC | string | Email addresses CCed on the mail |
| GoogleVault.Matter.Export.Results.BCC | string | Email addresses BCCed on the mail |
| GoogleVault.Matter.Export.Results.DateSent | string | The date the email was sent |
| GoogleVault.Matter.Export.Results.From | string | The sender of the email |
| GoogleVault.Matter.Export.Results.Subject | string | The subject of the email |
| GoogleVault.Matter.Export.Results.DateReceived | string | The date the email was received |
| GoogleVault.Matter.Export.Results.To | string | The address the email was sent to |
Command Example
!gvault-get-mail-results bucketName="85d7cacf-5d93-44e5-8d37-4ba6da342d02" viewID=0bebe0ec-ee41-4955-96b3-20d9408409c8/exportly-66079c37-0b33-4858-9239-7feead2199ae/mail_test_export412Z85Fs5q-metadata.xml
Context Example
Human Readable Output
17. Get the results of a Groups export
Get the results of a specified Groups export.
Base Command
gvault-get-groups-results
Input
| Argument Name | Description | Required |
|---|---|---|
| bucketName | Name of the bucket that holds the export | Required |
| viewID | The export view ID | Required |
| maxResult | Maximum number of results to return (a high threshold can slow down your browser), default is "30" | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| GoogleVault.Matter.Export.Results.CC | string | Email addresses CCed on the message |
| GoogleVault.Matter.Export.Results.BCC | string | Email addresses BCCed on the message |
| GoogleVault.Matter.Export.Results.DateSent | string | The date the message was sent |
| GoogleVault.Matter.Export.Results.From | string | The sender of the message |
| GoogleVault.Matter.Export.Results.Subject | string | The subject of the message |
| GoogleVault.Matter.Export.Results.DateReceived | string | The date the message was received |
| GoogleVault.Matter.Export.Results.To | string | The address the message was sent to |
Command Example
!gvault-get-groups-results bucketName="85d7cacf-5d93-44e5-8d37-4ba6da342d02" viewID="6e067f1d-7fac-4ab2-bd9f-eede4f32dd32/exportly-069b7a7b-0a3d-4fbf-b65d-fe54561e6eb2/Groups_Export_qQ3Ih4531388-metadata.xml" maxResult="30"
Context Example
Human Readable Output
