quarkslab/qazpt

1. What this repository is

QAZPT is a Python CLI tool for analyzing Entra ID permission inheritance. Its architecture is centered on building an in-memory identity/permission graph, resolving control relationships, then computing effective permissions and exporting results in several formats.

2. Primary entrypoints

The runtime entrypoints are qazpt/__main__.py and qazpt/main.py, which expose the qazpt command and its inheritance subcommand. The CLI is the orchestration layer: it parses flags, loads data, selects analysis mode, and routes output to tree/CSV/JSON/Neo4j exporters.

3. Boundary between data acquisition and analysis

The code is split into a “fetch/auth” side and an “analysis” side. qazpt/az/auth.py and the qazpt/az/ad/* package model Entra ID entities and permissions, while qazpt/core/* contains the permission-inheritance logic that operates on those models. This is an important architectural boundary: Microsoft Graph access and identity modeling are kept separate from graph algorithms.

4. Azure/Entra ID domain model

qazpt/az/ad/user.py, application/*, credentials.py, and permissions/* define the domain objects for users, app registrations, service principals, roles, and permission grants. These classes represent the raw security inventory that the analyzer consumes, including app roles, delegated permissions, and Entra ID role membership.

5. Core graph representation

qazpt/core/graph/ is the central internal data structure. graph.py, node.py, and condensation.py suggest a graph abstraction with explicit support for strongly connected components and condensation into a DAG. This graph is where ownership, service-principal linkage, FIC relationships, and role-based control edges are materialized.

6. Inheritance resolvers as graph builders

The qazpt/core/graph/resolvers/ package is the main “relationship discovery” layer. Each resolver contributes one inheritance path:

direct ownership, service principal of an app registration, federated identity credentials, Entra ID roles, and Microsoft Graph application roles. These resolvers are what turn raw directory objects into control edges in the graph.

7. Permission computation pipeline

qazpt/core/analysis.py and qazpt/core/linker.py likely orchestrate the end-to-end analysis: resolve links, build the graph, then compute transitive permission propagation. The README shows two analysis strategies: a legacy DFS approach and a Tarjan-based condensation approach that collapses cycles before bottom-up propagation.

8. Important algorithmic boundary: cyclic vs condensed traversal

The repository explicitly supports two traversal modes because inheritance graphs can contain cycles. The condensed DAG path is the default and is the more complete approach; the legacy DFS path exists for compatibility or troubleshooting. This affects diagramming because graph construction and graph evaluation are not the same phase.

9. Permission sources and effective permissions

qazpt/core/permissions/sets.py and sources.py appear to define the vocabulary of permission sets and their origins. The output distinguishes direct permissions from inherited ones, and also tracks “highly privileged” entities that stop transitive expansion because they already control the directory.

10. Output and visualization layer

qazpt/ui/visualization.py and qazpt/ui/colors.py handle human-readable rendering of the inheritance tree and gained permissions. qazpt/ui/neo4j_export.py is a separate export path that writes the analyzed graph into Neo4j, including nodes, labels, and relationships described in the README. This is a distinct sink from the CLI text/CSV/JSON outputs.

11. Caching and repeated runs

qazpt/utils/cache.py plus the --local-cache-dir CLI option indicate a local persistence layer for fetched directory data. Cache use is an architectural optimization boundary: it reduces repeated Microsoft Graph calls and lets analysis run on previously collected snapshots.

12. External dependencies and runtime shape

The project is a Python package built with pyproject.toml, tested with pytest, and distributed with container support via Dockerfile and docker-compose.yml. Neo4j is the only explicitly managed external service in the repo; Microsoft Graph/Entra ID is the data source implied by the auth and permission model.

13. Test architecture

The tests/data/* fixtures are structured as captured directory snapshots for different entity types and permissions scenarios. The tests appear to validate inheritance output against those fixtures, which means the test suite is focused on graph correctness and output stability rather than live integration with Microsoft Graph.

14. Diagramming summary

A good architecture diagram should show: CLI entrypoint → auth/data retrieval/cache → domain entity modeling → resolver-driven graph construction → condensation/transitive permission analysis → output/export paths (terminal tree, CSV/JSON, Neo4j). The key conceptual boundaries are source data vs analysis graph, and direct relationships vs computed effective permissions.