ROADtools for Microsoft Entra ID Security Assessment

ROADtools is an open-source framework for exploring and assessing Microsoft Entra ID environments, formerly known as Azure Active Directory (Azure AD). Security professionals use it to collect directory information, investigate identity configurations, and analyze potential security weaknesses during authorized assessments.

The framework includes ROADlib, a Python library for authentication and directory data handling, and ROADrecon, a tool that collects directory information into a local database for offline analysis. Together, they support identity security reviews from both Red Team and Blue Team perspectives.

ROADlib for Microsoft Entra ID Integration

ROADlib provides shared components for authentication and interaction with Microsoft identity services. Developers can also use it to build custom Python tools that work with ROADtools data.

• Authentication: Supports authentication workflows used to access authorized directory resources.
• Directory data models: Uses metadata-driven models to represent directory objects and their relationships.
• Python integration: Makes ROADlib functionality available to custom scripts and applications.
• Database compatibility: Provides components used by ROADrecon to create and process its collected directory data.

Import the library into a Python project with the appropriate module path:

from roadtools.roadlib import X

Replace X with the specific class or function required by your script. Review the project’s current documentation for supported interfaces and compatibility requirements.

ROADrecon for Entra ID Exploration

ROADrecon collects directory information and stores it in a database that can be examined separately from the live tenant. This makes it useful for reviewing identity relationships without repeatedly querying the directory during analysis.

• Local database: Stores collected directory objects in an SQLAlchemy-backed database.
• Asynchronous collection: Uses asynchronous HTTP requests to retrieve information efficiently.
• Web-based interface: Provides a browser interface for examining the local database.
• Plugin support: Allows collected data to be queried, analyzed, or exported into supported formats.
• Security investigations: Helps assess users, groups, applications, roles, and directory configuration.

For defenders, this data can help identify unexpected permissions, risky application assignments, and identity relationships that deserve further review. Collection results depend on the authenticated account’s permissions and the resources available to that account.

Install ROADtools with pip

The simplest installation method is to install ROADrecon from the Python Package Index. Use a virtual environment to keep its dependencies separate from other Python projects.

python3 -m venv roadtools-env
source roadtools-env/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install roadrecon

On Windows, activate the environment with roadtools-env\Scripts\activate instead of the Linux command. Check the official repository for the Python version supported by the release you intend to install.

Install from the GitHub Repository

For development or customization, clone the official repository and install the components in editable mode:

git clone https://github.com/dirkjanm/ROADtools.git
cd ROADtools
python3 -m pip install -e roadlib/
python3 -m pip install -e roadrecon/

Editable installation is useful when modifying source code because local changes are reflected in the installed package. For routine use, the PyPI installation is generally simpler.

Authenticate, Gather, and Analyze Data

ROADrecon separates its workflow into authentication, data collection, and analysis. For an authorized assessment, the following commands illustrate the basic sequence using interactive device-code authentication:

roadrecon --help
roadrecon auth --device-code
roadrecon gather
roadrecon gui

Follow the authentication prompts and sign in with an account authorized to access the target tenant. The device-code flow can accommodate multi-factor authentication when required by the tenant’s policies.

After collection, roadrecon gui opens the analysis interface for the local database. To explore available data-processing plugins, run:

roadrecon plugin -h

Review permissions before gathering data, protect the resulting database and authentication files, and avoid storing sensitive tenant information in publicly accessible locations. ROADtools supports security assessment, but its findings still require context and validation against the tenant’s actual configuration.

Explore the Adalanche directory analysis tool for a complementary perspective on identity relationships. For installation details, supported workflows, and updates, consult the official ROADtools GitHub repository and the ROADrecon getting-started guide.