Gmail
README
Gmail responder
This responder allows mailbox manipulation of Gsuite / Google Workspace accounts. The responder
can be used to implement message filters and delete message in a mailbox of a Gmail user.
Usage:
- You can block mail and domain observables
- Operations are carried out against all gmail addresses (dataType mail) in the case
- Example: john.doe@gmail.com or peter.parker@custom.domain
- Custom domain can be set in the responder config
- The message ID of deleted messages is added as tag to the respective gmail address (dataType mail)
- Messages can only be deleted via Gmail query syntax (datatype other); this enables one to bulk delete a lot of messages
- The filter ID of a blocked domain or mail gets added as tag to respective gmail address (dataType mail)
- All observables that get blocked/unblocked get a gmail:handled tag
Constrains:
- TheHive API key needs to provide read AND write permissions
- The Gmail user MUST be part of a Gsuite domain.
- Gsuite domain MUST have an service account enabled with domain-wide delegation.
- The service account MUST be configured with the following OAuth Scopes:
- https://mail.google.com/
- https://www.googleapis.com/auth/gmail.settings.basic
How to setup a Gmail service account
The responder needs a Gmail service account with domain-wide delegation. The rough setup steps are:
1. enable a service account via GCP
2. enable Gmail API
3. get service account client_id (oauth approval screens + domain-wide delegation needed)
4. change to Gsuite Admin panel
5. add third party app (security->API controls) with client_id
6. add domain-wide delegation with client_id
A detailed guideline for a service account setup can be found in the Google OAuth Python Client Docs.
Gmail_BlockDomain
Author: David Strassegger, @oscd_initiative
License: MIT
Version: 1.0
Supported data types:
- thehive:case_artifact
Registration required: N/A
Subscription required: N/A
Free subscription: N/A
Third party service: N/A
Description
Move emails from a given domain to trash
Configuration
| thehive_url |
URL for thehive instance |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| thehive_api_key |
API key for TheHive instance |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_domain |
Gsuite Domain |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_project_id |
GCP Project ID |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_private_key_id |
Service account private key id |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_private_key |
Service Account private key (PEM Format) |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_client_email |
Service Account E-Mail address |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_client_id |
OAuth Client ID |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
Gmail_BlockSender
Author: David Strassegger, @oscd_initiative
License: MIT
Version: 1.0
Supported data types:
- thehive:case_artifact
Registration required: N/A
Subscription required: N/A
Free subscription: N/A
Third party service: N/A
Description
Move emails from a given sender to trash
Configuration
| thehive_url |
URL for thehive instance |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| thehive_api_key |
API key for TheHive instance |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_domain |
Gsuite Domain |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_project_id |
GCP Project ID |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_private_key_id |
Service account private key id |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_private_key |
Service Account private key (PEM Format) |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_client_email |
Service Account E-Mail address |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_client_id |
OAuth Client ID |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
Gmail_DeleteMessage
Author: David Strassegger, @oscd_initiative
License: MIT
Version: 1.0
Supported data types:
- thehive:case_artifact
Registration required: N/A
Subscription required: N/A
Free subscription: N/A
Third party service: N/A
Description
Move a given message into the trash folder
Configuration
| thehive_url |
URL for thehive instance |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| thehive_api_key |
API key for TheHive instance |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_domain |
Gsuite Domain |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_project_id |
GCP Project ID |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_private_key_id |
Service account private key id |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_private_key |
Service Account private key (PEM Format) |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_client_email |
Service Account E-Mail address |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_client_id |
OAuth Client ID |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
Gmail_UnblockSender
Author: David Strassegger, @oscd_initiative
License: MIT
Version: 1.0
Supported data types:
- thehive:case_artifact
Registration required: N/A
Subscription required: N/A
Free subscription: N/A
Third party service: N/A
Description
Remove a message filter for a given sender
Configuration
| thehive_url |
URL for thehive instance |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| thehive_api_key |
API key for TheHive instance |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_domain |
Gsuite Domain |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_project_id |
GCP Project ID |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_private_key_id |
Service account private key id |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_private_key |
Service Account private key (PEM Format) |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_client_email |
Service Account E-Mail address |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_client_id |
OAuth Client ID |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
Gmail_UnblockDomain
Author: David Strassegger, @oscd_initiative
License: MIT
Version: 1.0
Supported data types:
- thehive:case_artifact
Registration required: N/A
Subscription required: N/A
Free subscription: N/A
Third party service: N/A
Description
Remove a message filter for a given domain
Configuration
| thehive_url |
URL for thehive instance |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| thehive_api_key |
API key for TheHive instance |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_domain |
Gsuite Domain |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_project_id |
GCP Project ID |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_private_key_id |
Service account private key id |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_private_key |
Service Account private key (PEM Format) |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_client_email |
Service Account E-Mail address |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |
| gmail_client_id |
OAuth Client ID |
| Default value if not configured |
N/A |
| Type of the configuration item |
string |
| The configuration item can contain multiple values |
False |
| Is required |
True |