Tia Zanella

Posted on Apr 8 • Originally published at osirisjson.org

OSIRIS JSON Producer for Microsoft Azure

#azure #solutionarchitect #opensource #tooling

The OSIRIS JSON Azure producer connects to Microsoft Azure via the Azure CLI (az) and generates OSIRIS JSON snapshots of your subscription topology - virtual networks, subnets, NICs, NSGs, load balancers, firewalls, VMs, and more.

To begin using OSIRIS JSON for Microsoft Azure, install the core dispatcher and the Azure producer:

go install go.osirisjson.org/producers/cmd/osirisjson-producer@latest
go install go.osirisjson.org/producers/cmd/osirisjson-producer-azure@latest

The core dispatcher lets you run osirisjson-producer azure .... Without it, invoke the vendor binary directly as osirisjson-producer-azure ....

Make sure $GOPATH/bin (or $HOME/go/bin) is in your PATH. See the getting started page for more install options.

Prerequisites

Install the Azure CLI
Authenticate: az login
The authenticate user must have a read permission to one or multiple target subscriptions, you can execute the producer on your local machine or decide to invoke the producer using a scheduled job using a service account with your favourite software or platform.

CLI usage

osirisjson-producer azure [flags]
osirisjson-producer azure template --generate

Single mode

Start by collecting one subscription that will be automatically saved as microsoft-azure-<timestamp>-<name>.json:

osirisjson-producer azure -S a1b2c3d4-e5f6-7890-abcd-ef1234567890

Interactive mode

Run without flags to get an interactive subscription picker:

osirisjson-producer azure

The producer discovers all accessible subscriptions and presents a numbered list. Select one or more (comma-separated) or type all.

Multi-subscription mode

Collect multiple subscriptions to an output directory:

# Specific subscriptions
osirisjson-producer azure -S sub-id-1,sub-id-2,sub-id-3 -o ./output

# All accessible subscriptions (auto-discover)
osirisjson-producer azure --all -o ./output

# All subscriptions in a specific tenant
osirisjson-producer azure --all --tenant f1e2d3c4-b5a6-9078-fedc-ba9876543210 -o ./output

Batch mode (CSV)

Generate a CSV template:

osirisjson-producer azure template --generate

Collect from a CSV file:

osirisjson-producer azure -s subscriptions.csv -o ./output

The CSV template uses these columns:

Column	Required	Description
`subscription_id`	yes	Azure subscription UUID
`subscription_name`	yes	Human-readable label (used as output filename)
`tenant_id`		Azure AD / Entra ID tenant UUID
`environment`		Deployment stage: `dv`, `np`, `pr` (development, non-production, production)
`region`		Filter to Azure region (empty = all regions)
`notes`		Free-text notes (ignored by producer)

Output hierarchy

Single mode: saves to microsoft-azure-<timestamp>-<name>.json in the current directory.

Multi/batch/all modes: organized by tenant and timestamp:

output/
  <TenantID>/
    <timestamp>/
      <SubscriptionName>.json

Each subscription produces a self-contained OSIRIS document. Cross-subscription references (e.g. VNet peerings to remote subscriptions) use deterministic resource IDs that consumers can correlate across documents.

Multi-tenant environments

Run the producer once per tenant. Each az login authenticates to one tenant. Use az login --tenant <tenant-id> to switch. The output hierarchy groups documents by tenant automatically.

Flags reference

Flag	Short	Description
`--subscription`	`-S`	Azure subscription ID(s), comma-separated
`--all`		Auto-discover all accessible subscriptions
`--source`	`-s`	CSV file with subscription targets
`--output`	`-o`	Output directory (required for multi/all/CSV mode)
`--tenant`		Azure AD / Entra ID tenant ID (optional)
`--region`		Filter to a specific Azure region (optional)
`--detail`		Detail level: `minimal` (default) or `detailed`
`--safe-failure-mode`		Secret handling: `fail-closed` (default), `log-and-redact`, `off`
`--version` / `-v`		Display version and exit
`--help`		Display help and exit

What it collects

The Azure producer queries the following resource types via the Azure CLI:

Minimal mode:

Azure Resource Type	OSIRIS Type	Description
Virtual Networks	`network.vpc`	VNets with address space, DNS, peerings
Subnets	`network.subnet`	Subnets with address prefixes, service endpoints
Network Interfaces	`network.interface`	NICs with IP configurations
Network Security Groups	`network.security.group`	NSGs with rule summaries
Route Tables	`osiris.azure.routetable`	UDRs with route counts
Public IP Addresses	`osiris.azure.publicip`	Public IPs with allocation method
Load Balancers	`network.loadbalancer`	L4 load balancers
Application Gateways	`network.loadbalancer`	L7 load balancers (app gateways)
Private Endpoints	`osiris.azure.privateendpoint`	Private link endpoints
VNet Gateways	`osiris.azure.gateway.vnet`	ExpressRoute / VPN gateways
NAT Gateways	`osiris.azure.gateway.nat`	Outbound NAT gateways
Azure Firewalls	`network.firewall`	Azure Firewall instances
DNS Zones	`osiris.azure.dns.zone`	Public DNS zones
Private DNS Zones	`osiris.azure.dns.privatezone`	Private DNS zones with VNet links
ExpressRoute Circuits	`osiris.azure.expressroute`	ExpressRoute circuits
Virtual Machines	`compute.vm`	VMs with size, power state
Resource Groups	`container.resourcegroup`	Resource groups as container resources

Detailed mode adds route table route details, load balancer rules, and extended properties.

OSIRIS JSON output structure for Microsoft Azure

{
  "$schema": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
  "version": "1.0.0",
  "metadata": {
    "generator": {
      "name": "osirisjson-producer-azure",
      "version": "0.1.0"
    },
    "scope": {
      "providers": ["azure"],
      "accounts": ["<tenant-id>"],
      "subscriptions": ["<subscription-id>"],
      "regions": ["westeurope", "eastus"]
    }
  },
  "topology": {
    "resources": [ ... ],
    "connections": [ ... ],
    "groups": [ ... ]
  }
}

Resource types

Resource types follow the OSIRIS JSON v1.0 specification. Standard types are used where defined; Azure-specific types use the osiris.azure.* namespace.

Standard types:

container.resourcegroup - Resource groups
network.vpc - Virtual networks
network.subnet - Subnets
network.interface - Network interfaces
network.security.group - Network security groups
network.loadbalancer - Load balancers (L4 and L7)
network.firewall - Azure Firewalls
compute.vm - Virtual machines

Custom types (osiris.azure.*):

osiris.azure.routetable - Route tables
osiris.azure.publicip - Public IP addresses
osiris.azure.privateendpoint - Private endpoints
osiris.azure.gateway.vnet - VNet gateways (VPN/ExpressRoute)
osiris.azure.gateway.nat - NAT gateways
osiris.azure.dns.zone - DNS zones
osiris.azure.dns.privatezone - Private DNS zones
osiris.azure.expressroute - ExpressRoute circuits

Connection types

network - Network connectivity (VNet peerings, NIC-to-subnet, NSG associations, DNS links, gateway connections)
contains - Containment (subnet-to-VNet membership)

Group types

logical.subscription - Top-level subscription group
logical.resourcegroup - Resource group groups (children of subscription)

Provider metadata

Every resource includes provider.type with the native ARM resource type (e.g. Microsoft.Network/virtualNetworks, Microsoft.Compute/virtualMachines). Cross-subscription peering stubs include provider.subscription with the remote subscription ID.

Resource IDs

Azure resource IDs follow the pattern azure::<ARM-resource-id>, using the full ARM resource ID as the native identifier. This ensures globally unique, deterministic IDs.

Examples

Single subscription

We are going to explore a single subscription in our tenant and generate from Microsoft Azure an OSIRIS JSON document.

osirisjson-producer azure -S a1b2c3d4-e5f6-7890-abcd-ef1234567890

OSIRIS JSON output document (trimmed):

{
  "$schema": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
  "version": "1.0.0",
  "metadata": {
    "generator": {
      "name": "osirisjson-producer-azure",
      "version": "0.1.0"
    },
    "scope": {
      "providers": ["azure"],
      "accounts": ["f1e2d3c4-b5a6-9078-fedc-ba9876543210"],
      "subscriptions": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
      "regions": ["westeurope"]
    }
  },
  "topology": {
    "resources": [
      {
        "id": "azure::/subscriptions/a1b2c3d4/resourceGroups/network-rg/providers/Microsoft.Network/virtualNetworks/hub-vnet",
        "type": "network.vpc",
        "name": "hub-vnet",
        "status": "active",
        "provider": {
          "name": "azure",
          "native_id": "/subscriptions/a1b2c3d4/resourceGroups/network-rg/providers/Microsoft.Network/virtualNetworks/hub-vnet",
          "type": "Microsoft.Network/virtualNetworks",
          "region": "westeurope",
          "subscription": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "tenant": "f1e2d3c4-b5a6-9078-fedc-ba9876543210"
        },
        "properties": {
          "resource_group": "network-rg",
          "address_space": ["10.0.0.0/16"],
          "dns_servers": ["10.0.0.4"]
        }
      },
      {
        "id": "azure::/subscriptions/a1b2c3d4/resourceGroups/compute-rg/providers/Microsoft.Compute/virtualMachines/web-vm-01",
        "type": "compute.vm",
        "name": "web-vm-01",
        "status": "active",
        "provider": {
          "name": "azure",
          "native_id": "/subscriptions/a1b2c3d4/resourceGroups/compute-rg/providers/Microsoft.Compute/virtualMachines/web-vm-01",
          "type": "Microsoft.Compute/virtualMachines",
          "region": "westeurope",
          "subscription": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "tenant": "f1e2d3c4-b5a6-9078-fedc-ba9876543210"
        },
        "properties": {
          "resource_group": "compute-rg",
          "vm_size": "Standard_D2s_v3",
          "power_state": "VM running"
        }
      }
    ],
    "connections": [
      {
        "source": "azure::/subscriptions/a1b2c3d4/.../subnets/default",
        "target": "azure::/subscriptions/a1b2c3d4/.../virtualNetworks/hub-vnet",
        "type": "contains",
        "direction": "forward"
      }
    ],
    "groups": [
      {
        "id": "azure::subscription::a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "type": "logical.subscription",
        "name": "my-nonprod-subscription",
        "children": [
          "azure::resourcegroup::network-rg",
          "azure::resourcegroup::compute-rg"
        ]
      },
      {
        "id": "azure::resourcegroup::network-rg",
        "type": "logical.resourcegroup",
        "name": "network-rg",
        "members": [
          "azure::/subscriptions/a1b2c3d4/.../virtualNetworks/hub-vnet"
        ]
      }
    ]
  }
}

Source: https://osirisjson.org/en/docs/producers/hyperscalers/microsoft-azure

DEV Community