# ROADtools: Azure AD and Entra Reconnaissance with ROADrecon and roadtx > ROADtools is a Python framework for dumping Azure AD and Entra data into a local SQL database and for exchanging the tokens that tenant issues. It is built for red and blue teams, and its install story is pip plus a wiki. **dirkjanm/ROADtools** — A collection of Azure AD/Entra tools for offensive and defensive security purposes - Repository: https://github.com/dirkjanm/ROADtools - Stars: 2,722 · Forks: 396 - Language: Python - License: MIT - Published: 2026-09-28 · Updated: 2026-09-28 · Language: en - Canonical page: https://hysenlabs.com/projects/dirkjanm-roadtools ## What ROADtools solves for Azure AD and Entra practitioners Querying Entra ID through the portal or through Microsoft Graph gives you one view at a time and no history. ROADtools takes a different position: pull the directory data down, write it to a database on your own disk, and query it afterwards. The repository describes itself as a framework to interact with Azure AD, split into a shared library (roadlib), an exploration tool (ROADrecon) and a token tool (ROADtools Token eXchange, or roadtx). The intended audience is stated in the repository description: offensive and defensive security purposes. That framing matters, because the same dump that a red team uses to find an over-permissioned service principal is the dump a blue team uses to see what a tenant actually contains. Neither role gets a hosted service here. You get Python packages, a local database file and an Angular interface that reads that file. roadtx covers a separate need. Azure AD issues several kinds of tokens, and roadtx is described as a tool for exchanging and using different types of them, with support for many authentication flows plus device registration and PRT related operations. If your problem is "I have one token and I need another", that is roadtx territory rather than ROADrecon territory. ## How the ROADrecon data flow works The mechanism is unusual and worth understanding before you commit. ROADlib's database model is generated automatically from the metadata definition of the Azure AD internal API. That means the schema is not hand-written against a documented public contract; it follows the API's own metadata, so the model tracks what that API exposes. ROADrecon then does three things in sequence. It creates an SQLAlchemy backed database on disk. It dumps all available information from the Azure AD graph into that database using asynchronous HTTP calls in Python. And it ships plugins that query the database and emit output in a useful format. The Angular front end is the part people recognise, but note where it sits: it queries the offline database directly. Analysis happens against your local copy, not against the tenant. That is the design's main advantage and its main constraint, since anything added to the tenant after your last dump is invisible until you dump again. One practical consequence of the async design is stated plainly: ROADrecon uses async Python features and is only compatible with Python 3.10 and newer. Development is done with Python 3.11, and tests run against versions up to Python 3.14. ## Installing ROADtools and running a first dump The simplest path is the published package. The README says stable versions install with pip and that this adds the roadrecon command to your PATH. ```bash pip install roadrecon ``` After that the roadrecon command should be available. The README does not document the dump subcommands inline; it points to a wiki page titled Getting started with ROADrecon for that, so treat the wiki as the reference for the authentication flags and the database path. For roadtx the equivalent one-liner is separate, and the README repeats the Python 3.10 or newer requirement for it. ```bash pip install roadtx ``` If you want the current master rather than the last release, every commit to master is built into a release by Azure Pipelines, which is how the README says you get the latest GUI without installing npm and its dependencies. Download the build artifacts, then install roadlib before roadrecon, in that order. ```bash pip install roadlib/ pip install roadrecon/ ``` The same ordering rule applies to roadtx: install roadlib first, then roadtx. For development work you can install either in editable mode, for example pip install -e roadlib/. Only the front end needs node and npm; from roadrecon/frontend/ the README gives npm install, npm start (or ng serve via the Angular CLI), and npm run build to place the JavaScript into ROADrecon's dist_gui directory. ## Where ROADtools stops being the right tool The offline database is the limitation. ROADrecon answers questions about the tenant as it was when you dumped it. It is not a live view, and the README does not describe any incremental sync, change feed or scheduled collection: the described flow is dump, then query. If your requirement is alerting on a directory change as it happens, this architecture is pointed the wrong way. Python version is a hard gate rather than a preference. ROADrecon requires 3.10 or newer because of its async implementation, and roadtx carries the same requirement. On a host pinned to an older interpreter, neither installs as described. Note also that the top-level setup.py still lists classifiers for Python 3.6 through 3.11 while the README's badge and prose say 3.10+, so read the README as the current statement and the classifier list as stale metadata. There is a second boundary around scope. ROADlib's model is generated from the metadata of the Azure AD internal API, which is not the same surface as the documented Microsoft Graph endpoints most integrations are written against. If you need a supported, versioned API contract for a production integration, this is not that; it is a tool that mirrors an internal API's metadata. Finally, the README is thin on operational detail. It does not document rollback, database migrations between versions, or what happens to an existing database when the generated model changes. Anyone planning to keep dumps over time has to answer that themselves. ## ROADtools compared with Microsoft Graph and the portal The real alternative for most teams is not another recon tool, it is the first-party path: query Microsoft Graph with your own script or use the Entra admin center directly. The difference in approach is not cosmetic. Graph gives you a supported, documented interface and you write the queries; ROADrecon gives you a pre-built schema derived from the internal API's metadata, a bulk dump, and plugins plus an Angular interface on top. That trade runs both ways. With Graph you decide what to fetch and you are bound by its permissions model and throttling. With ROADrecon you get breadth in one pass and a local database you can join against however you like, but you inherit a schema you did not design and a data set that ages the moment the dump finishes. roadtx has less of a direct first-party equivalent in day-to-day use. Exchanging token types, registering devices and working with PRTs are tasks the README assigns to roadtx specifically, and it is packaged as its own command with its own wiki page and a release blog post by the author. If your work is token manipulation rather than directory inventory, roadtx is the component to evaluate, and ROADrecon may be irrelevant to you entirely. ## Maintenance, licensing and the cost of upgrading The repository is not archived, and the last push was on 2026-08-05, which is recent enough that the project is still receiving changes. It is MIT licensed, which is permissive and places few obligations on how you use or redistribute it; the PyPI badges in the README also point at MIT. That is a statement about the licence text, not advice about your situation, and if you plan to redistribute a modified build you should read the LICENSE file at the repository root yourself. Upgrade cost is the part the README leaves open. Because the database model is auto-generated from API metadata, a new release can change the shape of the database your previous dump produced. The README does not describe a migration path, and no release notes are published alongside the packages, so there is no changelog to read before upgrading. The practical implication is that you should expect to re-dump rather than migrate, and you should test an upgrade against a throwaway database before pointing it at the one your analysis depends on. The multi-package layout adds a smaller cost. roadlib, roadrecon and roadtx version independently on PyPI, and the GitHub install instructions insist on installing roadlib first. Mixing a fresh roadtx with an older roadlib is the kind of mismatch the ordering rule exists to prevent. ## Conclusion Adopt ROADtools if you work with Azure AD or Entra from either side of a security engagement and you want the tenant data on local disk instead of behind a portal. Do not adopt it as an endpoint agent, a monitoring product or a compliance reporting layer: the README describes a library, an exploration tool and a token tool, and nothing about continuous collection. Before you install, confirm that pip resolves roadlib, roadrecon and roadtx on your Python, and read the two wiki pages for getting started with ROADrecon and for roadtx, because the README itself only points at them. ## FAQ ### What is ROADtools? It is a framework for interacting with Azure AD, made up of the roadlib library, the ROADrecon exploration tool and the roadtx token exchange tool. The repository describes it as a collection of Azure AD and Entra tools for offensive and defensive security purposes. ### How do I install ROADtools? Stable versions install from PyPI with pip install roadrecon, pip install roadtx, or pip install roadlib. Installing from GitHub means downloading the Azure Pipelines build artifacts and installing roadlib before roadrecon or roadtx. ### How do I use ROADtools? The README does not walk through usage itself; it links to a wiki page on getting started with ROADrecon and a separate wiki page for roadtx. ROADrecon creates a local SQLAlchemy database, dumps Azure AD graph information into it, and serves analysis through plugins and an Angular interface that reads that database. ## Sources - [dirkjanm/ROADtools on GitHub](https://github.com/dirkjanm/ROADtools) - [Issues](https://github.com/dirkjanm/ROADtools/issues) - [License: MIT](https://github.com/dirkjanm/ROADtools/blob/master/LICENSE) - [README](https://github.com/dirkjanm/ROADtools/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dirkjanm-roadtools