README
¶
arm-emulator
Coverage measures the unit suites. What catches consumer-facing defects is the real-client fleet — the
azCLI and the management SDKs — which no percentage scores; hence parity claims witnessed beside it: every claim of support names a test that exists and ran.
A clean-room, local emulator of the Azure Resource Manager control plane
(management.azure.com), scoped to what its sibling data planes need, part
of an emulator family built on one principle: the same trust
relationships as production.
- entra-emulator — the STS:
issues the tokens (including
aud: https://management.azure.com). - arm-emulator — the management plane: subscriptions, resource groups,
role assignments (
Microsoft.Authorization), vault resources (Microsoft.KeyVault/vaultsaccess policies), and Fabric capacities (Microsoft.Fabric/capacities). - azure-keyvault-emulator — the data plane that enforces those assignments on every request.
- fabric-emulator — consumes
Microsoft.Fabric/capacitiesover the family feed.
The point: az role assignment create and Microsoft's real management SDKs
(armauthorization, azure-mgmt-authorization, @azure/arm-authorization,
Azure.ResourceManager) run unmodified against this emulator, and the
assignments they write are genuinely enforced by the Key Vault data plane —
closing the last emulated gap in the family's authorization story.
Status
Working — the ARM envelope (resource-ID grammar, error shape,
ARM-audience tokens, anonymous cloud discovery), subscriptions and resource
groups, Microsoft.Authorization role definitions and assignments with real
scope inheritance, Microsoft.KeyVault/vaults with access policies, and
Microsoft.Fabric/capacities. Microsoft's own clients drive it unmodified —
the az CLI via az cloud register, and the armresources /
armauthorization / armkeyvault / armfabric SDKs — and the assignments
it stores are enforced by azure-keyvault-emulator's data plane. 98%+ coverage
with a CI floor; every green parity claim names its witness.
Install: go install github.com/calvinchengx/arm-emulator/cmd/arm-emulator@latest,
brew install calvinchengx/tap/arm-emulator,
winget install calvinchengx.arm-emulator, or the
ghcr.io/calvinchengx/arm-emulator image (see
docker-compose.yml for the entra-emulator pairing).
make up # entra-emulator + arm-emulator
make status # is the pair actually usable?
make doctor # what is missing from the toolchain?
Docs: https://calvinchengx.github.io/arm-emulator/ — start with the Quickstart, then Architecture, Authorization, Microsoft.Fabric and The family feed. What is real versus emulated is in the parity map.
Emulator family
arm-emulator is the ARM control plane. Its siblings are entra-emulator (the
STS whose tokens this one validates), azure-keyvault-emulator,
fabric-emulator and azure-apim-emulator.
To run them together, see azure-emulators: a composition-only repo
holding the family docker-compose.yml, the shared issuer wiring, and the
pinned image versions the members are tested against.
License
Apache-2.0. Clean-room: grounded solely in Microsoft's public documentation
and the pinned Azure/azure-rest-api-specs
OpenAPI specifications, with Microsoft's own management clients as the
conformance oracle — no Microsoft source.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
arm-emulator
command
Command arm-emulator runs the Azure Resource Manager control-plane emulator: subscriptions, resource groups, and Microsoft.Authorization role definitions and assignments, with ARM-audience bearer tokens validated against an Entra issuer (entra-emulator or a real tenant).
|
Command arm-emulator runs the Azure Resource Manager control-plane emulator: subscriptions, resource groups, and Microsoft.Authorization role definitions and assignments, with ARM-audience bearer tokens validated against an Entra issuer (entra-emulator or a real tenant). |
|
internal
|
|
|
abac
Package abac implements Azure's attribute-based access control conditions: the `condition` string a role assignment carries, in the version 2.0 language documented at learn.microsoft.com/azure/role-based-access-control/conditions-format.
|
Package abac implements Azure's attribute-based access control conditions: the `condition` string a role assignment carries, in the version 2.0 language documented at learn.microsoft.com/azure/role-based-access-control/conditions-format. |
|
arm
Package arm serves the Azure Resource Manager control plane: the resource-ID grammar, the ARM error envelope, api-version validation, ARM-audience token validation, and the providers the emulator family needs — Microsoft.Resources (subscriptions, resource groups) and Microsoft.Authorization (role definitions, role assignments).
|
Package arm serves the Azure Resource Manager control plane: the resource-ID grammar, the ARM error envelope, api-version validation, ARM-audience token validation, and the providers the emulator family needs — Microsoft.Resources (subscriptions, resource groups) and Microsoft.Authorization (role definitions, role assignments). |
|
auth
Package auth validates Entra bearer tokens the way real ARM does: signature against the issuer's JWKS, issuer match, the ARM audience, and expiry — with expiry checked against the emulator's controllable clock so token-lifetime scenarios are testable.
|
Package auth validates Entra bearer tokens the way real ARM does: signature against the issuer's JWKS, issuer match, the ARM audience, and expiry — with expiry checked against the emulator's controllable clock so token-lifetime scenarios are testable. |
|
clock
Package clock provides the emulator's controllable time source.
|
Package clock provides the emulator's controllable time source. |
|
config
Package config resolves runtime configuration from ARM_* environment variables with flag overrides applied by cmd.
|
Package config resolves runtime configuration from ARM_* environment variables with flag overrides applied by cmd. |
|
server
Package server wires the emulator: the ARM surface, the family feed, the /_emulator control surface (clock + faults), and health.
|
Package server wires the emulator: the ARM surface, the family feed, the /_emulator control surface (clock + faults), and health. |
|
store
Package store is the persistence layer: pure-Go SQLite holding resource groups, role assignments, and (from P1) tracked resources.
|
Package store is the persistence layer: pure-Go SQLite holding resource groups, role assignments, and (from P1) tracked resources. |
|
tlscert
Package tlscert generates the emulator's self-signed TLS certificate (localhost + the Key Vault wildcard), persisted under dataDir/tls when a data directory is configured so the fingerprint stays stable across runs.
|
Package tlscert generates the emulator's self-signed TLS certificate (localhost + the Key Vault wildcard), persisted under dataDir/tls when a data directory is configured so the fingerprint stays stable across runs. |