Publisher: Splunk
Connector Version: 2.4.0
Product Vendor: Google
Product Name: GMail
Product Version Supported (regex): ".*"
Minimum Product Version: 5.4.0
Integrates with G Suite for various investigative and containment actions
This app requires a pre-configured service account to operate. Please follow the procedure outlined
at this link to create a service account.
The following APIs will need to be enabled:
- AdminSDK
- GMail API
At the end of the creation process, the admin console should ask you to save the config as a JSON file. Copy the contents of the JSON file in the clipboard and paste it as the value of the key_json asset configuration parameter.
Once the service account has been created and APIs enabled, the next step is to configure scopes on
these APIs to allow the App to access them. Every action requires different scopes to operate, these
are listed in the action documentation.
To enable scopes please complete the following steps:
- Go to your G Suite domain's Admin console.
- 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 on the Service accounts page or in the service account JSON file (key named client_id ).
- In the One or More API Scopes field enter the list of scopes that you wish to grant access to the App. For example, to enable all the scopes required by this app enter: https://mail.google.com/, https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/gmail.readonly
- Click Authorize .
-
API provides created time of the email and gmail searches based on the received time of the email.
-
Use the large container numbers in asset to avoid any kind of data loss for emails which received at the same time.
Configuration:
- label - To fetch the emails from the given folder name (default - all folders).
Note:- Reply email in the email thread would not be ingested if you provide a specific label in the configuration (eg. Inbox). It will ingest the reply email only if you leave the label configuration parameter empty. - ingest_manner - To select the oldest first or newest first preference for ingestion (default - oldest first).
- first_run_max_emails - Maximum containers to poll for the first scheduled polling (default - 1000).
- max_containers - Maximum containers to poll after the first scheduled poll completes (default - 100).
- extract_attachments - Extract all the attachments included in emails.
- download_eml_attachments - Downloads the EML file attached with the mail.
- extract_urls - Extracts the URLs present in the emails.
- extract_ips - Extracts the IP addresses present in the emails.
- extract_domains - Extract the domain names present in the emails.
- extract_hashes - Extract the hashes present in the emails (MD5).
The below configuration variables are required for this Connector to operate. These variables are specified when configuring a GMail asset in SOAR.
| VARIABLE | REQUIRED | TYPE | DESCRIPTION |
|---|---|---|---|
| login_email | required | string | Login (Admin) email |
| key_json | required | password | Contents of Service Account JSON file |
| label | optional | string | Mailbox Label (folder) to be polled |
| ingest_manner | optional | string | How to ingest |
| first_run_max_emails | optional | numeric | Maximum Containers for scheduled polling first time |
| max_containers | optional | numeric | Maximum Containers for scheduled polling |
| extract_attachments | optional | boolean | Extract Attachments |
| extract_urls | optional | boolean | Extract URLs |
| extract_ips | optional | boolean | Extract IPs |
| extract_domains | optional | boolean | Extract Domain Names |
| extract_hashes | optional | boolean | Extract Hashes |
| download_eml_attachments | optional | boolean | Download EML attachments |
test connectivity - Validate the asset configuration for connectivity
list users - Get the list of users
run query - Search emails with query/filtering options
delete email - Delete emails
on poll - Callback action for the on-poll ingest functionality
get email - Retrieve email details via internet message id
Validate the asset configuration for connectivity
Type: test
Read only: True
Action uses the Admin SDK API to get a list of users. Requires authorization with the following scope: https://www.googleapis.com/auth/admin.directory.user.readonly.
No parameters are required for this action
No Output
Get the list of users
Type: investigate
Read only: True
Action uses the Admin SDK API to get a list of users. Requires authorization with the following scope: https://www.googleapis.com/auth/admin.directory.user.readonly.
The action will limit the number of users returned to max_items or (if not specified) 500. If the system has any more users, a next page token will be returned in action_result.summary.next_page_token. Use this value as input to page_token in subsequent calls to list users.
| PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
|---|---|---|---|---|
| max_items | optional | Max users to get (max 500) | numeric | |
| page_token | optional | Token to specify next page in list | string | gsuite page token |
| DATA PATH | TYPE | CONTAINS |
|---|---|---|
| action_result.status | string | |
| action_result.parameter.max_items | numeric | |
| action_result.parameter.page_token | string | gsuite page token |
| action_result.data.*.agreedToTerms | boolean | |
| action_result.data.*.archived | boolean | |
| action_result.data.*.changePasswordAtNextLogin | boolean | |
| action_result.data.*.creationTime | string | |
| action_result.data.*.customerId | string | |
| action_result.data.*.emails.*.address | string | email |
| action_result.data.*.emails.*.primary | boolean | |
| action_result.data.*.emails.*.type | string | |
| action_result.data.*.etag | string | |
| action_result.data.*.id | string | |
| action_result.data.*.includeInGlobalAddressList | boolean | |
| action_result.data.*.ipWhitelisted | boolean | |
| action_result.data.*.isAdmin | boolean | |
| action_result.data.*.isDelegatedAdmin | boolean | |
| action_result.data.*.isEnforcedIn2Sv | boolean | |
| action_result.data.*.isEnrolledIn2Sv | boolean | |
| action_result.data.*.isMailboxSetup | boolean | |
| action_result.data.*.kind | string | |
| action_result.data.*.languages.*.languageCode | string | |
| action_result.data.*.languages.*.preference | string | |
| action_result.data.*.lastLoginTime | string | |
| action_result.data.*.name.familyName | string | |
| action_result.data.*.name.fullName | string | |
| action_result.data.*.name.givenName | string | |
| action_result.data.*.nonEditableAliases | string | email |
| action_result.data.*.orgUnitPath | string | |
| action_result.data.*.phones.*.type | string | |
| action_result.data.*.phones.*.value | string | |
| action_result.data.*.primaryEmail | string | email |
| action_result.data.*.recoveryEmail | string | |
| action_result.data.*.suspended | boolean | |
| action_result.summary.next_page_token | string | gsuite page token |
| action_result.summary.total_users_returned | numeric | |
| action_result.message | string | |
| summary.total_objects | numeric | |
| summary.total_objects_successful | numeric |
Search emails with query/filtering options
Type: investigate
Read only: True
Action uses the GMail API to search in a users mailbox (specified in the email parameter).
Requires authorization with the following scope: https://www.googleapis.com/auth/gmail.readonly.
If none of the filtering parameters are specified the action will return all emails in the mailbox. If the query parameter is specified, all other filtering parameters are ignored.
The query parameter uses the same filtering options (operators) as the GMail search box. A brief description of these can be found at this link.
To page through results, execute the action without a page_token parameter and a valid max_results value. If the query matches more than max_results, the action will return a value in the action_result.summary.next_page_token data path. This value should be used as the input value to the page_token parameter in the next call to run query to get the next set of results.
| PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
|---|---|---|---|---|
| required | User's Email (Mailbox to search in) | string | email |
|
| label | optional | Label (to search in) | string | gmail label |
| subject | optional | Substring to search in Subject | string | |
| sender | optional | Sender Email address to match | string | email |
| body | optional | Substring to search in Body | string | |
| internet_message_id | optional | Internet Message ID | string | internet message id |
| query | optional | Gmail Query string | string | |
| max_results | optional | Max Results | numeric | |
| page_token | optional | Next page token | string |
| DATA PATH | TYPE | CONTAINS |
|---|---|---|
| action_result.status | string | |
| action_result.parameter.body | string | |
| action_result.parameter.email | string | email |
| action_result.parameter.internet_message_id | string | internet message id |
| action_result.parameter.label | string | gmail label |
| action_result.parameter.max_results | numeric | |
| action_result.parameter.page_token | string | |
| action_result.parameter.query | string | |
| action_result.parameter.sender | string | email |
| action_result.parameter.subject | string | |
| action_result.data.*.delivered_to | string | email |
| action_result.data.*.from | string | email |
| action_result.data.*.historyId | string | |
| action_result.data.*.id | string | gmail email id |
| action_result.data.*.internalDate | string | |
| action_result.data.*.labelIds | string | |
| action_result.data.*.message_id | string | internet message id |
| action_result.data.*.sizeEstimate | numeric | |
| action_result.data.*.snippet | string | |
| action_result.data.*.subject | string | |
| action_result.data.*.threadId | string | |
| action_result.data.*.to | string | email |
| action_result.summary.next_page_token | string | |
| action_result.summary.total_messages_returned | numeric | |
| action_result.message | string | |
| summary.total_objects | numeric | |
| summary.total_objects_successful | numeric |
Delete emails
Type: contain
Read only: False
Action uses the GMail API. Requires authorization with the following scope: https://mail.google.com.
| PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
|---|---|---|---|---|
| id | required | Message IDs to delete(Comma separated IDs allowed) | string | gmail email id |
| required | Email of the mailbox owner | string | email |
| DATA PATH | TYPE | CONTAINS |
|---|---|---|
| action_result.status | string | |
| action_result.parameter.email | string | email |
| action_result.parameter.id | string | gmail email id |
| action_result.data | string | |
| action_result.summary.deleted_emails | string | gmail email id |
| action_result.summary.ignored_ids | string | gmail email id |
| action_result.message | string | |
| summary.total_objects | numeric | |
| summary.total_objects_successful | numeric |
Callback action for the on-poll ingest functionality
Type: ingest
Read only: True
Requires authorization with the following scope: https://www.googleapis.com/auth/gmail.readonly.
| PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
|---|---|---|---|---|
| start_time | optional | Parameter Ignored in this app | numeric | |
| end_time | optional | Parameter Ignored in this app | numeric | |
| container_id | optional | Parameter Ignored in this app | string | |
| container_count | required | Maximum number of emails to ingest | numeric | |
| artifact_count | required | Maximum number of artifact to ingest | numeric |
No Output
Retrieve email details via internet message id
Type: investigate
Read only: False
Action uses the GMail API to search in a user's mailbox (specified in the email parameter). Use the run query action to retrieve internet message id.
Use extract attachments parameter to add attachments to vault and add corresponding vault artifacts.
Requires authorization with the following scope: https://www.googleapis.com/auth/gmail.readonly.
| PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS |
|---|---|---|---|---|
| required | User's Email (Mailbox to search) | string | email |
|
| internet_message_id | required | Internet Message ID | string | internet message id |
| extract_attachments | optional | Add attachments to vault and create vault artifacts | boolean |
| DATA PATH | TYPE | CONTAINS |
|---|---|---|
| action_result.status | string | |
| action_result.parameter.email | string | email |
| action_result.parameter.extract_attachments | boolean | |
| action_result.parameter.internet_message_id | string | internet message id |
| action_result.data.*.email_headers.*.arc_authentication_results | string | |
| action_result.data.*.email_headers.*.arc_message_signature | string | |
| action_result.data.*.email_headers.*.arc_seal | string | |
| action_result.data.*.email_headers.*.authentication_results | string | |
| action_result.data.*.email_headers.*.content_disposition | string | |
| action_result.data.*.email_headers.*.content_transfer_encoding | string | |
| action_result.data.*.email_headers.*.content_type | string | |
| action_result.data.*.email_headers.*.date | string | |
| action_result.data.*.email_headers.*.delivered_to | string | email |
| action_result.data.*.email_headers.*.dkim_signature | string | |
| action_result.data.*.email_headers.*.feedback_id | string | |
| action_result.data.*.email_headers.*.from | string | email |
| action_result.data.*.email_headers.*.message_id | string | |
| action_result.data.*.email_headers.*.mime_version | string | |
| action_result.data.*.email_headers.*.received | string | |
| action_result.data.*.email_headers.*.received_spf | string | |
| action_result.data.*.email_headers.*.reply_to | string | |
| action_result.data.*.email_headers.*.return_path | string | |
| action_result.data.*.email_headers.*.subject | string | |
| action_result.data.*.email_headers.*.to | string | email |
| action_result.data.*.email_headers.*.x_gm_message_state | string | |
| action_result.data.*.email_headers.*.x_google_dkim_signature | string | |
| action_result.data.*.email_headers.*.x_google_id | string | |
| action_result.data.*.email_headers.*.x_google_smtp_source | string | |
| action_result.data.*.email_headers.*.x_notifications | string | |
| action_result.data.*.email_headers.*.x_notifications_bounce_info | string | |
| action_result.data.*.email_headers.*.x_received | string | |
| action_result.data.*.from | string | email |
| action_result.data.*.historyId | string | |
| action_result.data.*.id | string | |
| action_result.data.*.internalDate | string | |
| action_result.data.*.labelIds | string | |
| action_result.data.*.parsed_html_body | string | |
| action_result.data.*.parsed_plain_body | string | |
| action_result.data.*.sizeEstimate | numeric | |
| action_result.data.*.snippet | string | |
| action_result.data.*.subject | string | |
| action_result.data.*.threadId | string | |
| action_result.data.*.to | string | email |
| action_result.summary.total_messages_returned | numeric | |
| action_result.message | string | |
| summary.total_objects | numeric | |
| summary.total_objects_successful | numeric |