Google Vault

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 Demisto

  1. Navigate to Settings > Integrations > Servers & Services .
  2. Search for Google Vault.
  3. 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
  4. Click Test to validate the URLs, token, and connection.

Create Authentication File Contents

You need to create an authentication file to authenticate Google Vault.

  1. Set up a new project in the Google APIs Console and activate Vault API service.
    https://code.google.com/apis/console
    image
  2. Set up authentication and authorization. For more information, see the Google documentation .
  • Select ENABLE APIS AND SERVICES > G Suite Vault API > ENABLE . image
  1. On the right side, click CREATE CREDENTIALS .
    Credentials are required to access and use the API.
  2. Select Which API are you using? > G Suite Vault API .
  3. From the 2nd drop-down list, under "Where will you be calling the API from?", choose "Other UI (e.g. Windows, CLI tool)
  4. Under "What data will you be accessing?", choose "Application Data".
  5. Click "What credentials do I need?"
    image
  6. Click Create credentials > Service account key .
  7. Under Service account, click Select > New service account .
    Make sure you select JSON for the key type.
  8. Make the account role "Owner" and click "Continue"
    image
  9. Download the JSON file that is given to you. Open it using Notepad and copy its contents.
  10. 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.
  11. 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.
    image
    In the One or More API Scopes field, enter the list of scopes that your application should be granted access to.
  12. 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
  13. Click Authorize .
    image

Commands


You can execute these commands from the Demisto 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.

  1. Create a Google Vault export: gvault-create-export-mail
  2. Create a matter: gvault-create-matter
  3. Create a Google Vault export for Drives: gvault-create-export-drive
  4. Update a matter state: gvault-matter-update-state
  5. Create a Google Vault export for Groups: gvault-create-export-groups
  6. Create a hold for a matter: gvault-create-hold
  7. Add a Held Account to a hold: gvault-add-heldAccount
  8. Remove a Held Account from a hold: gvault-remove-heldAccount
  9. Delete a hold: gvault-delete-hold
  10. Get a list of matters: gvault-list-matters
  11. Search for matters: gvault-get-matter
  12. List all holds for a matter: gvault-list-holds
  13. Get the status of exports: gvault-export-status
  14. Download an export: gvault-download-results
  15. Get the status of a Drives export: gvault-get-drive-results
  16. Get the results of a Mail export: gvault-get-mail-results
  17. 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

mail context

Human Readable Output

mail md

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

screen shot 2018-12-23 at 18 53 29

Human Readable Output

screen shot 2018-12-23 at 18 53 58

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

drive context

Human Readable Output

drive export

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

screen shot 2018-12-23 at 20 01 47

Human Readable Output

screen shot 2018-12-23 at 20 01 56

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

screen shot 2018-12-24 at 10 53 00

Human Readable Output

screen shot 2018-12-23 at 20 22 03

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

screen shot 2018-12-24 at 10 58 50

Human Readable Output

screen shot 2018-12-24 at 10 58 57

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

screen shot 2018-12-24 at 11 47 16

Human Readable Output

screen shot 2018-12-24 at 11 47 09

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

screen shot 2018-12-24 at 11 52 42

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

list matters - context

Human Readable Output

list matters-hr

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

get matter - context

Human Readable Output

get matter - hr

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

list hold - context

Human Readable Output

list hold - hr

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

export status - context

Human Readable Output

export status - hr

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

download export - hr

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

drive results - context

Human Readable Output

drive results - hr

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