Walkthrough guide for Google Threat Intelligence group administrators
Google Threat Intelligence's premium users are mainly split in two global flavors: regular users or "Members" and administrators or "Admins". Administrators have additional privileges to regular users, designed to manage their organization's Google Threat Intelligence group.
General notions
All actions restricted to administrators are accessible from the web interface under "My group" menu option, on the top right corner.
Group information
Here you can find the group's preferences including one of the most important group level parameters, the group's ID (refer to next image), which is required in multiple automation tasks.
Additional group related information is split in several tabs which allow the management of different types of features.
User information
Going down to the user level, they are listed in the USERS tab, where administrators can easily filter shown group members by security settings and user flavor and also by typing the name or email address of the user of interest.
Additionally, by clicking on a user name, you automatically pivot to the user's profile where user ID is shown next to the user's avatar. This ID is required in multiple automation tasks that are shown in next sections.
Service account information
In addition to users, a group could also have service accounts which are very useful for tasks automation since they are unaffected by people changes, as they are not tied to any specific individual and they don't require an email address to be created. This makes them a more reliable and consistent way to grant access to automation resources than user accounts.
Service accounts are listed on the Service accounts section available on the USERS tab where you can check their IDs.
API notions
In addition to the web interface there is a set of API v3 endpoints designed to automate most administrative tasks (more on this later) under the same server URL https://www.virustotal.com/api/v3/. These endpoints are shown on the "USERS & GROUPS ADMINISTRATION" section of the Google Threat Intelligence API v3 documentation - please note that NOT all of them require administrator privileges.
Their usage requires authentication/authorization through the admin's API key that can be found here (or on the navigator bar at the left -> API key menu option).
Everything a Google Threat Intelligence Admin can do
As we discussed, almost every action can be performed in 2 ways: via web interface and via API v3 requests. We grouped all actions reserved for administrator users in the following categories.
- 1. Group members management
- 3. Consumption
- 4. Additional services
1. Group members management
1.1. Getting group members
1.1.1. Getting the list of users and service accounts
Web interface => On the My group menu option -> USERS tab, the list of users is shown under the Group Members section -> User sub-section, and the list of service accounts under the Service accounts section. All of them can be exported by administrators through the Download button in several file formats, as shown in the following image.
The result file will include the following information: username, first name, last name, email and type to identify whether it is a user or a service account.
Google Threat Intelligence API => The endpoint /v3/groups/{id}/{relationship} returns the objects related to the group based on group's ID (check group ID) and relationship which identifies the type of objects to request and whose values in this case are "users" and "service_accounts".
Other endpoints provide the list of users and service accounts, but they don't provide the same information as the already mentioned one: /v3/groups/{id}/relationships/users and /v3/groups/{id}/relationships/service_accounts.
API example - refer to our GitHub repository, section Group members management.
1.2. Users management
1.2.1. Adding new user to an existing Google Threat Intelligence group
Web interface => From My group menu option -> USERS tab -> Add dropdown button -> User option, an administrator is able to create or add a new group member.
On the opened form, they have to specify the user's email address and user's flavor or role as administrator or common member before saving the request.
If a user is added to a group in VT but doesn't yet have an account, they will be sent an email invitation to create one. Upon account creation, the user will be automatically added to the group.
On the contrary, if the user already has an existing account, they will be automatically added to the group and receive a welcome email.
Google Threat Intelligence API => The /v3/groups/{id}/relationships/users endpoint allows administrators to add users to the group as common members. This endpoint requires the group ID (check group ID) as a parameter, and a list of user objects identified by their email addresses to convert in new group members as in the following example:
payload = {
"data": [
{"type":"user","id":"user_1_email_address"},
{"type":"user","id":"user_2_email_address"}
]
}
There's no specific endpoint for creating administrator members as in the web interface, although there's a way of granting admin privileges to common users when needed. Check out the "Managing users privileges or role" section.
API example - refer to our GitHub repository, section Group members management.
1.2.2. Adding new user to an existing Google Threat Intelligence group - automatically
Web interface => On My group menu option -> GROUP PREFERENCES section, the pen icon allows administrators to edit the Auto add emails parameter. This text box supports 2 types of inputs or conditions: complete email addresses and/or organization domain names regular expressions, with wildcards, (*@google.com, *@virustotal.com, *@mandiant.com), one entry per line.
When enabling this feature, new users whose email addresses meet one of the configured conditions, are automatically added to the group, inheriting group's default configurations.
The same can be done via My group menu option -> SETTINGS tab -> Group info section -> Auto add emails text box. Additionally, here administrators can enable the below checkbox to be notified every time a new user is added to their group as a group member.
Google Threat Intelligence API => The /v3/groups/{id} endpoint can be used to PATCH a Google Threat Intelligence group object based on its group ID. (Check group ID) The parameter associated with the automatically adding users to groups feature is data->attributes->auto_add_users. This parameter is a list of regular expressions (*@company_domain) and complete email addresses that are going to be checked with every new user, and those meeting any entry will be automatically added to the group as a new member. When using this endpoint, don't forget to specify the object 'type': 'group' in the payload parameter as in the following example:
payload = {
"data": {
"type": "group",
"attributes": {
"auto_add_users":["*@google.com", "*@virustotal.com", "*@mandiant.com", "email_addres1", "email_address2"]
}
}
}
Please note that since this parameter is rarely edited and the web interface is more than enough to cover it, we highly recommend editing this parameter manually through the web interface.
1.2.3. Removing user from a Google Threat Intelligence group
Web interface => The list of users is given on My group menu option -> USERS tab -> Group Members section -> User sub-section. Each user has a bin icon at the right, that allows administrators to remove it from the Google Threat Intelligence group, so that it is no longer a group member. Instead, it becomes a VirusTotal free user with limited access to VirusTotal's products.
Google Threat Intelligence API => The /v3/groups/{id}/relationships/users/{user_id} endpoint removes a given user from a given group, based on their identifiers. (Check group ID) (Check user ID) When removing a user from the group, it becomes a free user with limited access to VirusTotal's products.
API example - refer to our GitHub repository, section Group members management.
1.2.4. Managing user privileges or role
Web interface => The list of users is given on My group menu option -> USERS tab -> Group Members section -> User sub-section. Each of them has a dropdown option on the right showing the user flavor. From here, administrators are able to change user's privileges by choosing between Admin and Member roles.
Google Threat Intelligence API => The /v3/groups/{id}/relationships/administrators endpoint grants admin privileges to a list of users based on their email addresses and the group ID parameter. (Check group ID)
On the other hand, the /v3/groups/{id}/relationships/administrators/{user_id} endpoint revokes admin privileges of a given user based on its ID and the group ID. (Check user ID) (Check group ID)
API example - refer to our GitHub repository, section Group members management.
1.2.5. Managing user API allowance
Web interface => The list of users is given on My group menu option -> USERS tab -> Group Members section -> User sub-section. Each of them has a pen icon that allows administrators to change the user's "Daily API cap" that is shown.
Google Threat Intelligence API => The /v3/users/{id} endpoint can be used to PATCH a Google Threat Intelligence user object based on its ID. (Check user ID) This endpoint also serves to change an user daily API cap as in the following example:
payload = {
"data": {
"attributes": {
"quotas": {
"api_requests_daily": {
"allowed": 300
}
}
},
"type": "user"
}
}
API example - refer to our GitHub repository, section Group members management.
1.3. Service accounts management
1.3.1. Adding a new service account to an existing Google Threat Intelligence group
Web interface => Service accounts are very useful in automating enrichment and other automation tasks, since they are not tied to any specific individual.
From My group menu option -> USERS tab -> Add dropdown button -> Service Account option, administrators are able to create new service accounts.
On the opened form, administrators only have to specify the name or identifier that the new service account will receive, before saving the request.
Please note that the final name will be the result of concatenating the group ID with the typed name, separated by the "_" character. (Check group ID)
Google Threat Intelligence API => Although creating new service accounts is a very occasional activity and you might not need to automate it because the web interface serves well for this purpose, the /v3/groups/{id}/relationships/service_accounts endpoint can be used as well. It only requires the group ID (check group ID) and a new service account object with the ID that it will receive as in the following example:
payload = {
"data": [
{"id": "google_gti_bot", "type": "service_account"}
]
}
1.3.2. Removing a service account from a Google Threat Intelligence group
Web interface => The list of service accounts is given on My group menu option -> USERS tab -> Service accounts section. Each of them has a bin icon at the right, that allows administrators to delete the specific service account.
Please make sure that you are not going to interfere with any integration with Google Threat Intelligence by removing service accounts whose API keys are being used internally.
1.3.3. Getting a service accounts API key
Web interface => The list of service accounts is given on My group menu option -> USERS tab -> Service accounts section. Each of them has an icon for unhiding the API key and another icon for copying it to the clipboard. Only administrators are able to get the API key of a service account to use it on automation tasks such as IoCs enrichment.
Google Threat Intelligence API => Although checking service accounts API keys is a very occasional activity and you might not need to automate it because the web interface serves well to this purpose, the /v3/service_accounts/{id} endpoint can be used as well. It only requires the service account ID or name. (Check service account ID)
2. Group management
2.1. General settings
2.1.1. Editing organization name, domain name and avatar
Web interface => On the web platform, administrators can find 2 ways of modifying organization name and domain name.
- The first one is on My group menu option -> GROUP PREFERENCES. By selecting the pen icon administrators are able to edit Organization and Domain name parameters.
- The second way of editing this data is from My group menu option -> SETTINGS tab -> Group info section -> Organization and Domain name text boxes.
As for the group avatar, on My group menu option, at the top left is a Change avatar button that allows not only administrators but also common users to change group's avatar.
2.2. Security features
2.2.1. Editing all group members session timings
Web interface => On My group menu option -> SETTINGS tab -> Security controls section, administrators are able to define session maximum lifetime and inactivity time. Both of them are represented in seconds although they also show some default options by clicking on the input box.
When these times are exceeded, users are forced to re-authenticate.
2.2.2. Single Sign On - SSO
Web interface => On My group menu option -> SETTINGS tab -> Single sign-on section, administrators are able to configure the Identity provider for SSO. Through the dropdown option, administrators can enable one of the 4 SSO services already integrated or configure other preferred identity providers via Security Assertion Markup Language (SAML).
Please note that this only affects the authentication on the web platform. Google Threat Intelligence API authentication is not affected.
- Already integrated identity provider services
If users have accounts in any of the 4 services (Google, GitHub, Twitter, Microsoft), they can use those services to authenticate on our platform. For more information, refer to this document. Please note that users can always use one of these accounts without having to modify the Google Threat Intelligence enterprise group SSO configuration, but once configured, no one no longer will be able to authenticate on the platform via common credentials.
- SAML
For configuring SAML administrators can check out this guide example for Okta and replicate it to the preferred identity provider. The information needed to configure it is shown when selecting the Other (SAML) option in the Identity provider dropdown element.
Please note that for forcing users to only authenticate via SAML, a checkbox is provided. If this checkbox is not selected, users can use both methods of authentication: SAML and common credentials. We recommend allowing both authentication mechanisms during SAML configuration to avoid losing access to the platform in case of any misconfiguration.
2.3. Private Scanning settings
2.3.1. Editing Private Scanning retention period and storage region
Web interface => On My group menu option -> SETTINGS tab -> Private scanning section, administrators can configure the default Retention period days of files submitted to Private Scanning, their Storage region during their lifetime in Google Threat Intelligence's database and also some analysis preferences such as detonating the sample in dynamic analysis sandboxes to be not just statically but also dynamically analyzed. For this, other configurations are available such as enabling internet access to allow external communications of the file and intercepting HTTP/TLS communications. Additionally, there's an option for enabling live interactions of analysts with the sandbox where the sample is detonated.
This configuration will be used by default, although users are able to configure these parameters for each file they are submitting to Private Scanning directly from the submission form.
3. Consumption
3.1. Google Threat Intelligence features consumption
3.1.1. Getting current month group overall consumption
Web interface => On the My group menu option -> USAGE tab -> the Consumption current month section shows the consumption by features. In blue is highlighted consumption of the group over the current month, while in black it shows the overall allowance of the group. If any of the features is not available for the group, it will be identified by 0 allowance, while exceeded consumption will be highlighted in red.
Google Threat Intelligence API => The /v3/users/{id}/overall_quotas endpoint, shows an user's current month Google Threat Intelligence consumption summary but also the group's current month consumption summary, based on user ID. (Check user ID)
API example - refer to our GitHub repository, section Consumption.
3.1.2. Getting users individual consumption
Web interface => On My group menu option -> USAGE tab, there are several sections breaking down group's current month Google Threat Intelligence consumption by user:
- Search consumption by user
- Downloads consumption by user
- Livehunt rules consumption by user
- Retrohunt consumption by user
- Private scanning files consumption by user
- Private scanning URLs consumption by user
Google Threat Intelligence API => The /v3/users/{id}/overall_quotas endpoint not only shows a user's current month Google Threat Intelligence consumption summary but also the group's current month consumption summary based on a user ID. (Check user ID)
API example - refer to our GitHub repository, section Consumption.
3.2. Google Threat Intelligence API consumption
3.2.1. Getting group overall API consumption
Web interface => On My group menu option -> API tab, there are 2 sections showing the group's overall API consumption: Consumption last 30 days breaks down the group's last 30 days API consumption by day, and Consumption by endpoint shows previous day consumption by endpoint. For more granular details please use the Google Threat Intelligence APIv3.
Google Threat Intelligence API => The /v3/groups/{id}/api_usage endpoint shows a group's API usage broken down by day and endpoint, pointing out the endpoints that really consume API as well as those that do not (not_consuming_quota). The data available includes only the last 30 natural days and the required parameter is the group ID. (Check group ID) Additionally, you can specify the start day and last day parameters of the time range you want to track (yyyymmdd format).
API example - refer to our GitHub repository, section Consumption.
3.2.2. Getting users individual API consumption
Web interface => On the My group menu option -> API tab -> Consumption by user section shows previous day's consumption by user. For more granular details please use the APIv3.
Google Threat Intelligence API => The /v3/users/{id}/api_usage endpoint shows an user's API usage broken down by day and endpoint, pointing out the endpoints that really consume API as well as those that do not (not_consuming_quota). The data available includes only the last 30 natural days and the required parameter is the user ID. (Check user ID) Additionally, you can specify the start day and last day parameters of the time range you want to track (yyyymmdd format).
API example - refer to our GitHub repository, section Consumption.
4. Additional services
4.1. Attack Surface Management
4.1.1. Complete access to Attack Surface Management
Web interface => On Attack Surface Management left navigation menu option, administrators are able to access the ASM feature. This is available only for administrators and from here they can start their organization infrastructure security assessment.
When creating a project, an administrator becomes the owner of it, with the highest level of privileges to create collections of the project and run them, create groups of work, and manage members of working groups and roles or privileges of each of them and much more. For the complete information, please checkout the ASM section of the Google Threat Intelligence official documentation.
Google Threat Intelligence API => All important ASM tasks can be automated with the extensive set of Google Threat Intelligence API V3 endpoints that are completely explained in the ASM section of the Google Threat Intelligence API documentation.
Updated 22 days ago