Executive Summary

ROADtools is a publicly available toolkit for offensive and defensive security purposes that attackers have integrated into cloud attacks. The tool is designed to:

• Enumerate Entra ID
• Register devices in Entra ID
• Acquire, exchange and manipulate Microsoft Entra ID tokens

ROADtools is an open-source framework written in Python and built for red-teaming and research. It primarily targets the identity and authentication layers of Azure, and focuses on how accounts, applications and tokens operate in tenants.

To avoid detection, ROADtools operates through legitimate Microsoft APIs and can mimic typical traffic. Further defense evasion can be achieved by configuring request attributes such as user-agent strings. These capabilities have made ROADtools a valuable asset for attackers. Nation-state threat actors have used it in recent cloud intrusions for discovery, persistence and defense evasion. Attackers involved in a targeted phishing campaign in early 2025 used tooling that matches ROADtools' token management capabilities.

We provide an accessible overview of ROADtools, including how it evades detection and how nation-state threat actors and other adversaries misuse it. To aid defenders in protecting organizations against this threat, we also provide:

• Straightforward hunting queries that can reveal ROADtools usage
• Practical recommendations to detect and prevent the effectiveness of ROADtools within an environment

Palo Alto Networks customers are better protected from the threats described here through the following products and services:

• Cortex Cloud
• Cortex XDR and XSIAM
• The Unit 42 Cloud Security Assessment is an evaluation service that reviews cloud infrastructure to identify misconfigurations and security gaps.

If you think you might have been compromised or have an urgent matter, contact the Unit 42 Incident Response team.

Tool Overview

ROADtools is able to interact with Entra ID via legitimate APIs, and to customize user-agent strings — both of which help it to evade detection. The tool includes several modules — two of which we discuss in this article - and a set of shared libraries.

The ROADrecon Module

The roadrecon module is designed for internal discovery and enumeration. It gathers organizational data and identity information from Entra ID (formerly Azure Active Directory), including:

• Users
• Groups
• Roles
• Devices
• Service principals
• Applications
• Directory configurations

Results are stored in a local SQLite database that can be viewed through a custom web interface. This provides a graphical way to navigate the tenant and identify relationships or privileged objects that attackers could use for persistence or escalation. Figure 1 shows Entra ID Groups within the ROADrecon graphical web interface.

The roadrecon module originally queried the Azure AD Graph API to enumerate Azure AD resources. However, Microsoft has stated the Azure AD Graph API is being retired and all new or existing applications must migrate to Microsoft Graph API, which breaks a fundamental component of the original roadrecon functionality.

As of May 2026, an msgraph branch exists in the official ROADtools Github repository but has not been updated since April 2025. Subsequent development has continued in a separate, community-maintained fork, where partial roadrecon functionality has been implemented using the Microsoft Graph API. This fragmentation means users might encounter inconsistent functionality, while attackers can still enumerate Entra ID accounts and resources, as described in the Discovery section below.

The Token eXchange (roadtx) Module

The roadtx module facilitates token acquisition and exchange, enabling attackers to interact with Entra ID’s authentication endpoints. It supports several OAuth 2.0 and OpenID Connect authentication flows (sign-in methods), including:

• Entering a device code from another device (device code flow)
• Reusing a refresh token to get new access
• Allowing an application to request access on behalf of a user (known as an on-behalf-of or OBO flow)

The output of roadtx is typically a set of OAuth 2.0 access and refresh tokens in JSON format, which can be used to authenticate against Microsoft cloud services. The roadtx module can be used to register devices with Entra ID, replay stolen tokens and manipulate token lifecycles. This capability allows attackers to persist in an environment and bypass multi-factor authentication (MFA).

Supporting both roadrecon and roadtx is roadlib, the library layer that handles low-level authentication and API requests. The roadlib module provides the core functionality for ROADtools. It abstracts much of Microsoft’s authentication complexity, allowing an attacker or researcher to script token requests and API calls without having to know every OAuth detail.

This module is flexible and can be pointed at different API endpoints, including custom or non-Microsoft endpoints. This feature makes ROADtools easy to adapt to other security tooling and enables it to target a wider range of authentication systems.

With the above functionality in mind, the rest of this article explains how adversaries leverage ROADtools to perform their operations and what defenders can do to protect against ROADtools.

Threat Actor Usage and Industry Targeting

The use of ROADtools has evolved from a red-team utility to an attack tool. Industry reports illustrate that various nation-state threat actors are leveraging the tool to conduct malicious activity:

• Early observation of a nation-state actor operationalizing the ROADtools framework came in late 2021, when Microsoft reported on activity by Cloaked Ursa (aka Midnight Blizzard or APT29). The group’s campaigns began with highly targeted spear phishing to gain initial access. Cloaked Ursa subsequently leveraged ROADtools to conduct discovery and enumerate victims’ Azure AD (now Entra ID) environments.
• Microsoft reported the Iranian state-sponsored threat actor Curious Serpens (aka Peach Sandstorm, APT33) using ROADtools in malicious operations in 2023. After gaining initial access through password spray attacks, the threat actor used tools, including ROADtools for internal discovery.
• Volexity reported in 2025 on a targeted phishing campaign during which a state-affiliated threat actor, which it calls UTA0355, was able to register a rogue device with Entra ID. Attackers were able to acquire a new token with full access to the Microsoft Graph API. The tooling Volexity reported matched the roadtx module’s token management capabilities.

MITRE ATT&CK® Tactics

MITRE ATT&CK provides a structured way to describe how attackers operate. Organizing findings by MITRE ATT&CK Tactics, Techniques and Procedures enables defenders to:

• Map attacker behaviors to a common language
• Compare those behaviors across intrusions
• Prioritize detections and mitigations based on the actions attackers take

In the sections that follow, we reference specific MITRE techniques to show how ROADtools components enable those behaviors, including:

• Persistence: T1098.005 Account Manipulation – Device Registration
• Defense Evasion: T1550 Use Alternate Authentication Material
• Discovery: T1087 Account Discovery

Persistence

Technique: T1098.005 Account Manipulation – Device Registration (Figure 2).

The ROADtools roadtx module can register new devices in Entra ID. Attackers register or join devices to gain a durable means of persistence through a controlled account. Registration allows a rogue device to appear as a legitimate object in the Entra ID device inventory. Depending on the Entra ID configuration, a registered or joined device may also enable attackers to bypass MFA and conditional access policies (CAPs).

To register a device using roadtx, an attacker must first obtain valid credentials. The attacker can then use these credentials with roadtx to authenticate via one of the supported authentication flows, to acquire an access token for the Azure device registration service (urn:ms-drs:enterpriseregistration.windows[.]net).

After authentication, the attacker runs roadtx again, which calls the Azure device registration API to create a new device entry. The roadtx module writes the device certificate and key to the local file system and registers the device in Entra ID. Note that roadtx has default values for some command parameters. Unless specified otherwise, the devices will be registered as:

• OS: Windows
• OS Version: 10.0.19041.928
• Name: DESKTOP-<RANDOM 8 DIGITS>

While these default values can be useful for detection purposes, they are also simple to change. All defaults can be viewed by running roadtx device -h from the command line, or by viewing them in the roadtx source code.

Figure 3 shows how an attacker uses a previously acquired refresh token to authenticate to the Azure device registration service and register a new device with the name mydevice.

Defense Evasion

Technique: T1550 Use Alternate Authentication Material (Figure 4).

Attackers try to acquire tokens because those tokens let them access company data and cloud services on behalf of a user or service, often without triggering a new interactive sign-in, enabling activity that blends in with legitimate API usage. Tokens allow attackers to move laterally, copy data and obtain persistent access in a target environment, bypassing interactive controls like MFA.

By leveraging a Primary Refresh Token (PRT), an attacker can maintain access to cloud applications by silently obtaining new access tokens in the background, which are then used in subsequent API requests, eliminating the need for repeated logins. The roadtx prt command allows attackers to acquire such a PRT. Full details of the process for registering a device and PRT acquisition are described by the ROADtools author.

Using roadtx, attackers can automate the misuse of a stolen PRT. This automation involves performing the token exchange and API call workflows that are needed in order to acquire fresh user access tokens and to call services such as Microsoft Graph non-interactively. A single device-bound PRT compromise can provide an attacker with persistent, programmatic access across the tenant.

Discovery

Technique: T1087 Account Discovery (Figure 5).

Attackers perform account discovery to map an environment, identify high-value accounts and find lateral movement or privilege escalation targets. Ongoing efforts within the ROADtools community to adopt the Microsoft Graph API have enabled continued use of roadrecon for account discovery.

To use roadrecon for discovery, attackers must first authenticate to acquire the refresh and access tokens that allow access to the Microsoft Graph API. The authentication must use a client ID that has the necessary permissions for all the Microsoft Graph API endpoints that they wish to enumerate.

The Microsoft Graph API version supports a new roadrecon command-line parameter -mg that points the code to the Microsoft Graph API to enumerate resources such as:

• /users
• /groups
• /devices
• /servicePrincipals
• /applications

This enumeration enables attackers to harvest account names, devices, roles, group membership and service-principal metadata. These are written to the local SQLite database as previously noted.

Figure 6 below lists devices registered in Entra ID as shown in the ROADtools custom web interface. This example is from a test environment but serves to illustrate the ease of discovering resources in the environment. Note the OS Version 10.0.19041.928 circled in red. As described earlier, this is currently the default value that roadtx uses when registering a device, and is different than the OS version for the other hosts, making it a good indicator of ROADtools activity.

Defender Perspective

The discussion so far has focused on how adversaries can misuse ROADtools. It is equally important to understand what defenders can do in response. Preventive controls and active threat hunting offer organizations multiple opportunities to detect and disrupt these techniques.

Preventive Controls to Limit Token Misuse

ROADtools is challenging for defenders to detect because it operates within expected behavior. It does not exploit buffer overflows or drop binaries onto hosts, but instead uses the authentication flows and APIs that organizations rely on every day. Implementing layered identity defenses can limit how attackers misuse ROADtools. Defenders should consider the following controls:

• Enable Entra ID token protection: Enabling token protection reduces the value of stolen refresh tokens. Binding refresh tokens to a specific device (token protection/“client claims”) is one of the most direct ways to prevent the replay or misuse of tokens obtained by roadtx. This makes it harder for adversaries to export and reuse tokens from other hosts.
• Restrict device code flow via conditional access: CAPs can restrict risky flows, such as device code, where they are not needed. Attackers use roadtx to misuse device code flow because it works well for script-based attacks. Blocking or restricting this flow to only trusted scenarios (like registered devices, trusted IP address ranges or specific apps) cuts off an attack path.
• Audit OAuth apps regularly: Auditing applications for delegated and application permissions that have been granted helps eliminate excessive privileges that attackers target. Attackers can use roadtx to obtain tokens for any registered app if permissions are in place. Custom or abandoned apps with overly broad Microsoft Graph, SharePoint or Exchange permissions are prime targets. A cloud security posture management (CSPM) or cloud-native application protection platform (CNAPP) solution can help defenders conduct regular reviews, to reduce the attack surface.
• Limit privilege exposure: Even if an attacker manages to obtain a token, organizations can greatly reduce potential damage by using privileged identity management (PIM) or privileged access management (PAM) to limit standing privileges and conditional access to require step-up authentication. These measures enforce least privilege and minimize the impact of a compromised account.
• Correlate logs across multiple sources: Detection and threat hunting depend on event correlation. Prepare for this by bringing Azure audit logs, Microsoft Graph API activity logs, sign-ins and Office 365 activity together into a security information and event management (SIEM) platform to provide the visibility needed to spot anomalous API usage.

These controls help prevent and detect common attack techniques and lay the groundwork for effective threat hunting. With these controls in place, defenders can more effectively search for suspicious token usage, authentication flows or discovery activity before they escalate into compromise.

An attacker using roadtx for authentication is using valid credentials. As such, defenders must establish a baseline of normal activity for that user or resource to understand whether a sign-in is malicious or legitimate.

Microsoft Entra ID Protection provides two important reports for this purpose:

• Risky sign-in reports surfaces attempted and successful user access activities where the legitimate owner might not have performed the sign-in
• Risky user reports surfaces user accounts that might have been compromised (e.g., a leaked credential that was detected or the user signing in from an unexpected location in the absence of planned travel)

Hunting ROADtools Activity

With preventive controls in place, the next step is to actively look for signs of misuse. Threat hunting in this context goes beyond reviewing alerts. It requires systematically searching for anomalous patterns in device joins and registrations, and for token issuance and Graph API calls that could indicate suspicious roadtx or roadrecon activity.

Device Registration

Start by looking for evidence that adversaries are running ROADtools to register or join devices into Entra ID. Inspect audit events that relate to device registration, highlighting which users or service principals initiated the action. The broader objective is to detect when an attacker attempts to establish persistence in Entra ID by creating and controlling unauthorized devices.

Token Misuse

Next, look for evidence of token misuse. We have discussed how roadtx and roadlib are designed to acquire and refresh tokens programmatically. To defenders, that activity looks different from a standard browser or app sign-in. These differences include:

• Scripted user agents
• Service principals authenticating outside of expected patterns
• Automated sign-in behavior that doesn’t resemble human use

The goal is to flag when an attacker is misusing tokens to blend in with legitimate activity while running scripted, malicious roadtx commands against the tenant. For example, an attacker may run roadtx with a version of python-requests (a Python library that supports HTTP) that is not usually seen in an organization's environment. Or even simpler, sign-ins via Python might not be expected in an organization at all, or only from certain IP ranges.

Microsoft Graph API

Finally, look for evidence of attackers using roadrecon to access the Microsoft Graph API and enumerate users, groups, service principals, applications and devices. These discovery activities are not limited to ROADtools and can be performed directly through Microsoft Graph API calls using custom scripts or other tooling.

For defenders, the key is to watch Microsoft Graph API logs for bursty, repetitive queries against those endpoints. Legitimate administrators rarely perform these actions in bulk. Defenders must migrate any roadrecon detections that rely on Azure AD Graph activity logs to use Microsoft Graph activity logs instead.

Conclusion

ROADtools is an example of the dual use of security tooling. Released as a framework to interact with Azure AD for offensive and defensive security purposes, attackers have adopted ROADtools as a platform for real-world intrusions against Microsoft cloud environments. We have seen how its features map to MITRE ATT&CK techniques, and identified the alignment with attacker tactics of persistence, defense evasion and discovery.

For defenders, the challenge lies in ROADtools’ use of legitimate APIs and authentication flows. ROADtools activity can easily blend into normal cloud operations. Identifying malicious use of this toolset requires careful attention to anomalies in user agents, IP addresses, activity type and Graph API usage. Mitigations like token protection, conditional access policies, cloud security audits and privileged identity management provide additional layers of defense.

Palo Alto Networks Protection and Mitigation

Palo Alto Networks customers are better protected from the threats described here through the following products and services:

• Cortex Cloud endpoint protection can help protect organizations from threats expressed within this article. Cortex Cloud 2.1 can detect and prevent malicious operations through the use of behavioral and AI enabled analytics to detect when cloud and container endpoints are targeted. Additionally, it can detect when cloud platform IAM policies associated with those targeted endpoints are being misused and alert teams when assets are vulnerable to these threats.
• Cortex XDR and XSIAM customers can use the hunting, investigation and detection queries below to identify potentially suspicious activity related to the threats discussed in this article. In addition, Cortex Identity Threat Detection and Response (ITDR) can help in detecting authentication and credential-based threats by analyzing user activity from multiple data sources including endpoints, network firewalls, Active Directory, identity and access management solutions, and cloud workloads.
• The Unit 42 Cloud Security Assessment is an evaluation service that reviews cloud infrastructure to identify misconfigurations and security gaps.

If you think you may have been compromised or have an urgent matter, get in touch with the Unit 42 Incident Response team or call:

• North America: Toll Free: +1 (866) 486-4842 (866.4.UNIT42)
• UK: +44.20.3743.3660
• Europe and Middle East: +31.20.299.3130
• Asia: +65.6983.8730
• Japan: +81.50.1790.0200
• Australia: +61.2.4062.7950
• India: 000 800 050 45107

Palo Alto Networks has shared these findings with our fellow Cyber Threat Alliance (CTA) members. CTA members use this intelligence to rapidly deploy protections to their customers and to systematically disrupt malicious cyber actors. Learn more about the Cyber Threat Alliance.

Hunting, Investigation and Detection Queries

The queries below are designed to help Palo Alto Networks customers hunt for, investigate, and identify potentially suspicious activity using Cortex XDR. Results returned by these queries should not be considered inherently malicious and require further analysis to determine their significance.

Cortex XQL Queries

Device Registration

The XQL query below hunts for threat actors using ROADtools to register or join devices in Entra ID, focusing on audit events that reveal initiating identities and potential attempts to establish persistence through unauthorized device creation. Depending on the environment in which this is run and in what timeframe, the query could return a large set of results. A 24-hour timeframe spanning any suspicious activity is a good starting point. Look for results from unexpected or suspicious locations or identities. Also, look for any device names that do not conform to expected naming conventions in your organization.

Token Misuse

The following query looks for evidence of token misuse, as roadtx and roadlib generate authentication patterns that might differ from regular user sign-ins. Focus on anomalies like scripted user agents, unusual service principal activity, and automated sign-in behavior – such as unexpected Python-based access – that may indicate threat actors executing malicious actions.

Microsoft Graph API

The following XQL query looks for roadrecon activity by monitoring Microsoft Graph API logs for high-volume, repeated enumeration of users, groups and applications – behavior uncommon for legitimate administrators. We built the following hunt query to detect this enumeration pattern, revealing when a threat actor is systematically mapping out the directory. The API call threshold should be adjusted to values indicating outliers in your organization.

Indicators

User-Agent string in HTTP headers of network traffic:

• roadtools
• python-requests/<version>

Additional Resources

• dirkjanm/ROADtools: A collection of Azure AD/Entra tools for offensive and defensive security purposes – GitHub
• Microsoft Graph Community Supported Fork for RoadRecon – GitHub
• Block authentication flows with Conditional Access policy – Microsoft
• Conditional Access: Grant – Microsoft
• How Token Protection Enhances Conditional Access Policies – Microsoft
• How it works: Device registration - Microsoft Entra ID – Microsoft
• Important Update: Azure AD Graph retirement – Microsoft
• Microsoft identity platform and the OAuth 2.0 device authorization grant flow – Microsoft
• Migrate your apps from Azure AD Graph to Microsoft Graph – Microsoft
• Protecting Tokens in Microsoft Entra ID – Microsoft
• Review permissions granted to enterprise applications – Microsoft
• What is device identity in Microsoft Entra ID? – Microsoft
• Understanding Primary Refresh Token (PRT) in Microsoft Entra ID – Microsoft
• NOBELIUM targeting delegated administrative privileges to facilitate broader attacks – Microsoft Security
• Peach Sandstorm password spray campaigns enable intelligence collection at high-value targets – Microsoft Security
• Cloaked Ursa Archives – Palo Alto Networks Unit 42
• Detecting Threats with Microsoft Graph Activity Logs – Palo Alto Networks Unit 42
• Threat Brief: Escalation of Cyber Risk Related to Iran (Updated June 30) – Palo Alto Networks Unit 42
• Phishing for Codes: Russian Threat Actors Target Microsoft 365 OAuth Workflows – Volexity