Walkthrough guide for VirusTotal group administrators
VirusTotal’s premium users are split in two flavors: regular users and administrators. Administrators have additional privileges to regular users, designed to manage the VirusTotal group assigned to them.
General notions
All actions restricted to administrators are accessible from the web interface under the "VT Enterprise 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 management of different types of features. Please note that depending on the group's configuration and acquired services, the number of tabs available for each group can vary.
User information
Going down to the user level, they are listed in the USERS tab, where administrators can easily filter shown group members by user flavor, by 2FA enablement 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 endpoints designed to automate most administrative tasks (more on this later). These endpoints are shown on the “VT ENTERPRISE ADMINISTRATION” section of the 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 top right corner of the web interface -> API key menu option).
Everything a VT Admin can do
As we discussed, almost every action in VT 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
- 2. Group management
- 3. Consumption
1. Group members management
1.1. Getting group members
1.1.1. Getting the list of users and service accounts
Web interface => On the VT Enterprise group menu option -> USERS tab, the list of users is shown under the Group members 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 account or a service account.
VirusTotal 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 the VT group
Web interface => From the VT Enterprise group menu option -> USERS tab -> Add dropdown button -> User option, an administrator is able to create a new group member.
On the opened form, they have to specify the user's email address and user’s flavor or privileges 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.
VirusTotal 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’ section.
API example - refer to our GitHub repository, section Group members management.
1.2.2. Adding new user to the VT group - automatically
Web interface => On the VT Enterprise group menu option -> GROUP PREFERENCES section, the pen icon allows administrators to edit the Auto add emails config parameter. This text box supports 2 types of inputs or conditions: complete email addresses and/or organization domain names regular expressions, with wildcards, (*@virustotal.com or *@google.com), one entry per line.
When enabling this feature, new VirusTotal users whose email address meet one of the configured conditions, are automatically added to the group, inheriting group's default configurations.
The same can be done via VT Enterprise 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.
VirusTotal API => The /v3/groups/{id} endpoint can be used to PATCH a VirusTotal group object based on its group ID. (Check group ID) The parameter associated with the automatically adding users to groups feature is _data->attributes->autoadd_users. This parameter is a list of regular expressions (*@company_domain) and complete email addresses that are going to be checked with every new VT 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":["*@virustotal.com", "*@google.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 the VT group
Web interface => The list of users is given on the VT Enterprise group menu option -> USERS tab -> Group members section. Each user has a bin icon at the right, that allows administrators to remove it from the VT group, so that it is no longer a group member. Instead, it becomes a free user with limited access to VirusTotal’s products.
VirusTotal 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
Web interface => The list of users is given on the VT Enterprise group menu option -> USERS tab -> Group members 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 options.
VirusTotal 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 the VT Enterprise group menu option -> USERS tab -> Group members section. Each of them has a pen icon that allows administrators to change the user’s Daily API cap that is shown next to the pen icon.
VirusTotal API => The /v3/users/{id} endpoint can be used to PATCH a VirusTotal 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 the VT 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 the VT Enterprise 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.
VirusTotal 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": "vt_enrichment", "type": "service_account"}
]
}
1.3.2. Removing a service account from the VT group
Web interface => The list of service accounts is given on the VT Enterprise 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 VT by removing service accounts whose API key is being used internally.
1.3.3. Getting a service accounts API key
Web interface => The list of service accounts is given on the VT Enterprise 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.
VirusTotal 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 the VT Enterprise 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 the VT Enterprise group menu option -> SETTINGS tab -> Group info section -> Organization and Domain name text boxes.
As for the group avatar, on the VT Enterprise 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 the VT Enterprise 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 the VT Enterprise 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. VirusTotal 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 VT 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 PS retention period and storage region
Web interface => On the VT Enterprise group menu option -> SETTINGS tab -> Private scanning section, administrators can configure the default Retention period days of files submitted to Private Scanning and also their Storage region during their lifetime in VirusTotal’s database.
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.
2.4. Invoice settings
2.4.1. Getting invoice notifications
Web interface => On the VT Enterprise group menu option -> SETTINGS tab -> Group info section -> Send invoices to text box, administrators can configure a list of email addresses to be notified of every new invoice.
Please note that this is available only if the organization is paying VirusTotal Enterprise via credit card.
Additionally, invoices can be accessed by administrators from the VT Enterprise group menu option -> INVOICES tab.
3. Consumption
3.1. VirusTotal enterprise features consumption
3.1.1. Getting current month group overall enterprise consumption
Web interface => On the VT Enterprise group menu option -> VT ENTERPRISE tab -> the Consumption current month section shows the consumption by VirusTotal feature. 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.
VirusTotal API => The /v3/users/{id}/overall_quotas endpoint, shows an user's current month VT enterprise consumption summary but also the group's current month VT enterprise consumption summary, based on user ID. (Check user ID)
API example - refer to our GitHub repository, section Consumption.
3.1.2. Getting users individual enterprise consumption
Web interface => On the VT Enterprise group menu option -> VT ENTERPRISE tab, there are 4 sections breaking down group’s current month VT enterprise consumption by user:
- Search consumption by user
- Downloads consumption by user
- Livehunt rules consumption by user
- Retrohunt consumption by user
VirusTotal API => The /v3/users/{id}/overall_quotas endpoint not only shows a user's current month VT enterprise consumption summary but also the group's current month VT enterprise consumption summary based on a user ID. (Check user ID)
API example - refer to our GitHub repository, section Consumption.
3.2. VirusTotal API consumption
3.2.1 Getting group overall API consumption
Web interface => On the VT Enterprise group menu option -> VT 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 VirusTotal APIv3.
VirusTotal 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 60 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 VT Enterprise group menu option -> VT API tab -> Consumption by user section shows previous day’s consumption by user. For more granular details please use the APIv3.
VirusTotal 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 60 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.
Updated about 2 months ago