This guide outlines three methods for precisely querying Credential Alerts from the Digital Threat Monitoring (DTM) API. Learn how to retrieve alerts by type, a specific monitor ID, or an aggregated bucket ID to build more efficient security integrations.
How to Query for Credential Alerts
When querying Credential alerts there are multiple methods to receive results.
- You can query based on the alert type.
- You can query based on the Credential Monitor ID.
- You can query based on the aggregated alert bucket ID.
Things to know before starting:
Pagination
The Digital Threat Monitoring (DTM) API paginates alert returns, with a default of 10 alerts per page. Users can increase this to 25 alerts per page using the "size" query parameter. For queries exceeding 25 alerts, subsequent pages are accessed via a HTTP Link Header in the API response, which provides the URI for the next results page. This Link URI must be used precisely as provided, as it contains essential pagination context, and no other query parameters are permitted when fetching subsequent pages through it.
Aggregated Alert Buckets
Credential Alerts are grouped into distinct buckets, with each Compromised Credential Monitor generating its own bucket of alerts. To view these bucket IDs, set the "buckets" query parameter to "true." By default, this parameter is "false," in which case all child aggregated alerts are returned.
Querying based on the alert type:
Receiving Credential Alerts through the DTM alert endpoint is the most direct approach. However, if you have multiple Compromised Credential Monitors, all alerts from all monitors will be received.
To obtain these alerts via the API, query the DTM alert endpoint. Set the “alert_type” query parameter to “Compromised Credentials”. Optionally, set the status to "new" to retrieve only unread alerts.
It is crucial not to use the “buckets” query parameter for this method. If used, set it to “false” to ensure you receive the alerts and not just the aggregated alert bucket IDs.
Example
https://www.virustotal.com/api/v3/dtm/alerts?status=new&alert_type=Compromised%20Credentials
Querying based on the Credential Monitor ID:
If you have multiple Compromised Credential Monitors, and want to receive the alerts from a specific monitor, this is the method to use.
To get your monitors’ IDs you can retrieve it via the Portal by clicking on the monitor of interest. The monitor ID will then be the last part of the URL.
Example:
https://advantage.mandiant.com/dtm/monitors/<monitor id>
Monitor IDs can be retrieved via the API, either directly by querying the monitor endpoint or by querying the alert endpoint for compromised credentials.
If querying the alert endpoint, consider setting the "buckets" parameter to "true." This will result in a smaller response while still providing the monitor ID values.
Once you have the monitor ID, query the alert endpoint and specify the "monitor_id" query parameter. For this method, do not use the "buckets" query parameter, or set it to "false." Otherwise, you will receive aggregated alert bucket IDs instead of the individual alerts.
Example:
https://www.virustotal.com/api/v3/dtm/alerts?monitor_id=<monitor ID>&buckets=true&status=new&alert_type=Compromised%20Credentials
Querying based on the aggregated alert bucket ID:
This method allows you to receive alerts from a specific bucket of aggregated alerts, particularly useful if you manage multiple Compromised Credential Monitors. To obtain the aggregated alert bucket ID, query the alert endpoint for Compromised Credentials and set the "buckets" parameter to "true."
Example:
The bucket’s ID will be the first “id” field in the response body of the “alerts” and before the “monitor_id”.
Example:
{
"alerts":
{
"id": "c4huif0mhcmiku5g",
"monitor_id": …
Once you receive your bucket ID you will query the alert aggregates endpoint using the bucket ID.
Example:
https://www.virustotal.com/api/v3/dtm/alerts/<bucket ID>/aggregates?status=new
https://www.virustotal.com/api/v3/dtm/alerts/c4huif0mhcmiku5g/aggregates?status=new
Conclusion
Aggregated credential alerts can be obtained through various methods, depending on your specific needs and use case. Options include requesting all alerts simultaneously, alerts from a particular monitor, or most precisely, alerts from a specific bucket.
Author: Eric Wadlin, Google Cloud Security Technical Solutions Consultant