|
Check out our Walkthrough guide for VirusTotal group administrators! |
VirusTotal administrators’ tasks are key for the good health of the groups they manage. Unfortunately it is not always clear the best way to do this or that task. But we heard our beloved community, and we created the definitive guide for everything a VirusTotal group administrator might need to know, including use cases, examples, where to find everything in the GUI and how to automate tasks using the API, including scripts ready to use in our GitHub repository.
Introducing the walkthrough guide for VirusTotal group admins
General notions
The guide begins with general notions and a quick overview of the VT Enterprise group web interface.
In particular, we need to know where to retrieve IDs for groups, users and service accounts, as they are required for any VirusTotal API v3 interaction. The administrator’s API key is required for VirusTotal API authentication/authorization.
- Group ID: on the VT Enterprise group portal, the GROUP PREFERENCES section shows your Group ID.
- User ID: on the VT Enterprise group portal, the Group members section lists the group's users. By clicking on any of them, you automatically pivot to USER PROFILE where the user's ID is shown near the user's avatar.
- Service account ID: on the VT Enterprise group portal, the Service accounts section lists the group’s service accounts by their IDs.
- VirusTotal user API key: there are 2 ways of getting your API key from the landing page as in the below image.
Use cases
The second part of the guide describes every action a VirusTotal admin can perform, splitted by sections for easier reference:
- Group members management
In this section you will find how to manage users and service accounts by adding or removing them to/from the group, how to download a list of members and how to manage users privileges.
- Group management
This section focuses on group-level configurations that may also affect users, such as active session timings and Single Sign On (SSO) security features.
- Consumption
At this section you will find information about one of the most requested topics, which is quota and consumption.
Each use case has a descriptive title to easily identify what you are looking for, the Web interface section describing use cases in the GUI, and details on VirusTotal API v3 endpoints that can be used to automate the use case, including API examples linking to our GitHub repository for most cases.
Enforcing security - 2FA
As an example, and focusing on a security perspective, let’s say that we want to obtain all users in our group without 2FA enabled.
In the VT Enterprise group web interface you will find the USERS tab, and under the Group members section there is a Filter by dropdown with the View only users without 2FA option:
The same can be automated with the API with a simple script.
"""
**DISCLAIMER:**
Please note that this code is for educational purposes only.
It is not intended to be run directly in production.
This is provided on a best effort basis.
Please make sure the code you run does what you expect it to do.
"""
import requests
def get_users_without_2fa(apikey, group_id):
"""
Getting users objects related to a group by group ID, filtering by 2fa_enabled = false.
Requested users attributes: first_name,last_name,email.
VT API endpoint reference: https://developers.virustotal.com/reference/groups-relationships
"""
users = []
url = f"https://www.virustotal.com/api/v3/groups/{group_id}/users?attributes=first_name,last_name,email&filter=2fa_enabled:false"
headers = {"accept": "application/json", "x-apikey": apikey}
while url:
res = requests.get(url, headers=headers)
res.raise_for_status()
res = res.json()
for el in res["data"]:
users.append(
f"username:{el['id']},"
f"first_name:{el['attributes'].get('first_name','')},"
f"last_name:{el['attributes'].get('last_name','')},"
f"email:{el['attributes'].get('email','')}"
)
url = res.get("links", {}).get("next", None)
return users
**DISCLAIMER:**
Please note that this code is for educational purposes only.
It is not intended to be run directly in production.
This is provided on a best effort basis.
Please make sure the code you run does what you expect it to do.
"""
import requests
def get_users_without_2fa(apikey, group_id):
"""
Getting users objects related to a group by group ID, filtering by 2fa_enabled = false.
Requested users attributes: first_name,last_name,email.
VT API endpoint reference: https://developers.virustotal.com/reference/groups-relationships
"""
users = []
url = f"https://www.virustotal.com/api/v3/groups/{group_id}/users?attributes=first_name,last_name,email&filter=2fa_enabled:false"
headers = {"accept": "application/json", "x-apikey": apikey}
while url:
res = requests.get(url, headers=headers)
res.raise_for_status()
res = res.json()
for el in res["data"]:
users.append(
f"username:{el['id']},"
f"first_name:{el['attributes'].get('first_name','')},"
f"last_name:{el['attributes'].get('last_name','')},"
f"email:{el['attributes'].get('email','')}"
)
url = res.get("links", {}).get("next", None)
return users
For this we used the /v3/groups/{group_id}/{relationship} endpoint, which refers to ‘users’ relationship, filtering by “2fa_enabled” as “false” and requesting “first_name”, “last_name” and “email” attributes for each of them.
Check it out on our GitHub repository!
Enforcing security - privileges are granted where required
It is very important to monitor that admin privileges are only granted to users who require them to perform their jobs. Tracking admin privileges on a regular basis is a very healthy task.
When using the VirusTotal web portal, the only difference to the previous example is the filter to be applied, which in this case is View only admin users.
This task can be automated. The following Python script compares the users with admin privileges against a given list of administrators and reports any anomalies:
"""
**DISCLAIMER:**
Please note that this code is for educational purposes only.
It is not intended to be run directly in production.
This is provided on a best effort basis.
Please make sure the code you run does what you expect it to do.
"""
import requests
def get_possible_unauthorized_admins(apikey, group_id, authorized_admins):
"""
Getting users objects (administrators) related to a group by group ID.
Requested users attributes: first_name,last_name,email.
VT API endpoint reference: https://docs.virustotal.com/reference/get-group-administrators
"""
unauthorized_admins = []
url = f"https://www.virustotal.com/api/v3/groups/{group_id}/administrators?attributes=first_name,last_name,email"
headers = {"accept": "application/json", "x-apikey": apikey}
while url:
res = requests.get(url, headers=headers)
res.raise_for_status()
res = res.json()
for el in res["data"]:
if el["id"] not in authorized_admins:
unauthorized_admins.append(
f"username: {el['id']}, "
f"first_name: {el['attributes'].get('first_name', '')}, "
f"last_name: {el['attributes'].get('last_name', '')}, "
f"email: {el['attributes'].get('email', '')}"
)
url = res.get("links", {}).get("next", None)
return unauthorized_admins
**DISCLAIMER:**
Please note that this code is for educational purposes only.
It is not intended to be run directly in production.
This is provided on a best effort basis.
Please make sure the code you run does what you expect it to do.
"""
import requests
def get_possible_unauthorized_admins(apikey, group_id, authorized_admins):
"""
Getting users objects (administrators) related to a group by group ID.
Requested users attributes: first_name,last_name,email.
VT API endpoint reference: https://docs.virustotal.com/reference/get-group-administrators
"""
unauthorized_admins = []
url = f"https://www.virustotal.com/api/v3/groups/{group_id}/administrators?attributes=first_name,last_name,email"
headers = {"accept": "application/json", "x-apikey": apikey}
while url:
res = requests.get(url, headers=headers)
res.raise_for_status()
res = res.json()
for el in res["data"]:
if el["id"] not in authorized_admins:
unauthorized_admins.append(
f"username: {el['id']}, "
f"first_name: {el['attributes'].get('first_name', '')}, "
f"last_name: {el['attributes'].get('last_name', '')}, "
f"email: {el['attributes'].get('email', '')}"
)
url = res.get("links", {}).get("next", None)
return unauthorized_admins
For this we have used /v3/groups/{group_id}/administrators endpoint referring to ‘administrators’ relationship where requested “first_name”, “last_name” and “email” attributes for each of them. Additionally, the ‘authorized_admins’ list is used to filter out authorized admins.
Check it out on our GitHub repository!
Wrapping up
With these new resources, we aim to assist VirusTotal group administrators in their day-to-day duties. The documentation is extensive enough to cover everything they can do on the web interface and provides ways of automation to get the same data as from the web portal, but through raw Python scripts when possible.
We hope you find this as useful as we do. If you have any questions, feedback or new use cases we can assist you with, please do not hesitate to contact us.
Happy management!