ROADtools

(Rogue Office 365 and Azure (active) Directory tools)

ROADtools is a framework to interact with Azure AD. It consists of a library (roadlib) with common components, the ROADrecon Azure AD exploration tool and the ROADtools Token eXchange (roadtx) tool.

ROADlib

ROADlib is a library that can be used to authenticate with Azure AD or to build tools that integrate with a database containing ROADrecon data. The database model in ROADlib is automatically generated based on the metadata definition of the Azure AD internal API. ROADlib lives in the ROADtools namespace, so to import it in your scripts use from roadtools.roadlib import X

ROADrecon

ROADrecon is a tool for exploring information in Azure AD from both a Red Team and Blue Team perspective. In short, this is what it does:

• Uses an automatically generated metadata model to create an SQLAlchemy backed database on disk.
• Use asynchronous HTTP calls in Python to dump all available information in the Azure AD graph to this database.
• Provide plugins to query this database and output it to a useful format.
• Provide a web interface (FastAPI backend, React frontend) that queries the offline database directly for its analysis.

ROADrecon uses async Python features and is only compatible with Python 3.10 and newer (development is done with Python 3.11, tests are run with versions up to Python 3.14).

Installation

There are multiple ways to install ROADrecon:

Using a published version on PyPi
Stable versions can be installed with pip install roadrecon. This will automatically add the roadrecon command to your PATH.

Using a version from GitHub
Every commit to master is automatically built into a release version with Azure Pipelines. This ensures that you can install the latest version of the GUI without having to install npm and all it's dependencies. You can download the roadlib and roadrecon build files from the Azure Pipelines artifacts (click on the button "1 Published". The build output files are stored in ROADtools.zip. You can either install the .whl or .tar.gz files directly using pip or unzip both and install the folders in the correct order (roadlib first):

pip install roadlib/
pip install roadrecon/

You can also install them in development mode with pip install -e roadlib/.

Developing the front-end
If you want to make changes to the front-end (React, in roadrecon/frontend-react/), you will need to have node (22) and npm installed. Then install the components from git:

git clone https://github.com/dirkjanm/roadtools.git
pip install -e roadlib/
pip install -e roadrecon/
cd roadrecon/frontend-react/
npm ci

Run the API with uvicorn roadtools.roadrecon.api.app:create_app --factory --reload --port 8000 (it reads the database from $ROADRECON_DB, default roadrecon.db; set ROADRECON_READ_ONLY=1 to never write to it), then npm run dev from roadrecon/frontend-react/. Vite serves the front-end on http://127.0.0.1:5173 and forwards /api to port 8000. The built front-end is committed in roadrecon/roadtools/roadrecon/dist_gui, so installing from a clone needs no node. After changing the front-end, rebuild it with npm run build and commit dist_gui along with the source.

Alternatively, roadrecon/compose.yaml runs everything in containers (podman or docker), from the roadrecon/ directory:

podman compose run --rm py python roadrecon/tests/gendb.py -o roadrecon/.dev/roadrecon.db   # synthetic database
podman compose up                  # built GUI + API on http://127.0.0.1:5000 (ROADRECON_DB overrides the database)
podman compose up api web          # development: API with --reload + Vite on http://127.0.0.1:5173
VITE_MOCK=1 podman compose up web  # front-end only, on mock data
podman compose up legacy           # old GUI on the same database, http://127.0.0.1:5001
podman compose run --rm py pytest roadrecon/tests -q
podman compose run --rm node npm run build

Using ROADrecon

Authenticate with roadrecon auth, then gather data:

• roadrecon gather: the directory, from the Azure AD Graph;
• roadrecon pimgather: Privileged Identity Management role assignments;
• roadrecon iggather: Identity Governance (access packages);
• roadrecon azgather: Azure Resource Manager access and resources;
• roadrecon gatherall: all of the above.

Then start the GUI with roadrecon gui (or roadrecon-gui) and open http://127.0.0.1:5000. Options: -d for the database file (default roadrecon.db), --host and --port (default 127.0.0.1:5000), and --read-only to never write to the database (by default, indexes are added on start-up).

The GUI shows the following (pages and tabs whose data was not gathered are hidden):

• A dashboard with tenant statistics, tenant information, directory settings and the Entra ID licence (P2 / P1 / Free), security defaults and seamless SSO.
• Lists of users, groups, devices, administrative units, service principals, applications, directory roles, application role assignments, OAuth2 permission grants and MFA status (methods registered, and whether a Conditional Access policy requires MFA), with server-side search, filters, sorting and CSV/JSON export.
• A page per object, with its properties, its relations (members, owners, roles, PIM, Azure roles, access packages, Conditional Access policies) and the raw object.
• Conditional Access policies with every reference resolved to a link (authentication strengths included), the users in scope of a policy, and the named locations with the policies that use them.
• A Conditional Access sign-in check: pick a user or workload identity, a target resource, a location, platform, client app and risks to see which policies apply or may apply, and whether the sign-in is blocked, needs MFA or other grant and session controls.
• A SQL page to run read-only queries directly against the database, with built-in queries.
• A global search across all objects (⌘K / Ctrl+K).

The API documentation is served on /docs.

See this Wiki page on how to get started.

ROADtools Token eXchange (roadtx)

roadtx is a tool for exchanging and using different types of Azure AD issued tokens. It supports many different authentication flows, device registration and PRT related operations. For an overview of the tool, see the roadtx Wiki.

Installation

There are multiple ways to install roadtx. Note that roadtx requires Python 3.10 or newer.

Using a published version on PyPi
Stable versions can be installed with pip install roadtx. This will automatically add the roadtx command to your PATH.

Using a version from GitHub You can clone this repository and install roadlib and then roadtx to make sure you have the latest versions of both the tool and the library:

pip install roadlib/
pip install roadtx/

You can also install them in development mode with pip install -e roadtx/.

Using roadtx

See the Wiki on how to use roadtx. See also the release blog.