Producer OSIRIS JSON per Microsoft Azure
Il producer Azure di OSIRIS JSON si connette a Microsoft Azure tramite la Azure CLI (az) e genera snapshot OSIRIS JSON della topologia delle tue sottoscrizioni. A partire dalla versione v0.4.0, il producer copre i livelli di rete, calcolo, storage, identità, database, container, integrazione, osservabilità e backup, incluse le relative relazioni di dipendenza tra risorse (Private Endpoint verso destinazioni PaaS, App Service verso App Insights, Log Analytics, RSV, Backup Vault verso elementi protetti, AKS verso subnet e pool di nodi, ecc.).
Per iniziare a usare OSIRIS JSON per Microsoft Azure, installa il dispatcher core e il producer OSIRIS JSON per Microsoft Azure:
go install go.osirisjson.org/producers/cmd/osirisjson-producer@latest
go install go.osirisjson.org/producers/cmd/osirisjson-producer-azure@latest
Il dispatcher core consente di eseguire osirisjson-producer azure .... Senza di esso, richiama direttamente il binario del vendor come osirisjson-producer-azure ....
Assicurati che $GOPATH/bin (o $HOME/go/bin) sia nel tuo PATH. Consulta la pagina getting started per ulteriori opzioni di installazione.
Prerequisiti
- Installa la Azure CLI
- Autenticati:
az login - L’utente autenticato deve avere il ruolo Reader (o un permesso di lettura equivalente) sulla/e sottoscrizione/i di destinazione. Per la raccolta completa dei dati, incluse le route effettive, l’utente deve avere anche il permesso
Microsoft.Network/networkInterfaces/effectiveRouteTable/action(incluso in Network Contributor e nei ruoli superiori). Se questo permesso non è presente, il producer salta la raccolta delle route effettive con un log INFO e continua normalmente.
Puoi eseguire il producer sulla tua macchina locale oppure richiamarlo tramite un job pianificato con un account di servizio sulla piattaforma che preferisci.
Utilizzo della CLI
osirisjson-producer azure [flags]
osirisjson-producer azure template --generate
Modalità singola
Inizia raccogliendo una sottoscrizione, che verrà salvata automaticamente come microsoft-azure-<timestamp>-<name>.json:
osirisjson-producer azure -S a1b2c3d4-e5f6-7890-abcd-ef1234567890
Modalità interattiva
Esegui senza flag per ottenere un selettore interattivo delle sottoscrizioni:
osirisjson-producer azure
Il producer rileva tutte le sottoscrizioni accessibili e presenta un elenco numerato. Seleziona usando numeri singoli (1,3,5), intervalli (30-55), combinazioni (1,3,30-55) oppure digitando all.
Modalità multi-sottoscrizione
Raccogli più sottoscrizioni in una directory di output:
# Sottoscrizioni specifiche
osirisjson-producer azure -S sub-id-1,sub-id-2,sub-id-3 -o ./output
# Tutte le sottoscrizioni accessibili (rilevamento automatico)
osirisjson-producer azure --all -o ./output
# Tutte le sottoscrizioni in un tenant specifico
osirisjson-producer azure --all --tenant f1e2d3c4-b5a6-9078-fedc-ba9876543210 -o ./output
Modalità batch (CSV)
Genera un modello CSV:
osirisjson-producer azure template --generate
Raccogli da un file CSV:
osirisjson-producer azure -s subscriptions.csv -o ./output
Il modello CSV utilizza queste colonne:
| Colonna | Obbligatoria | Descrizione |
|---|---|---|
subscription_id | sì | UUID della sottoscrizione Azure |
subscription_name | sì | Etichetta leggibile (usata come nome del file di output) |
tenant_id | UUID del tenant Azure AD / Entra ID | |
environment | Fase di distribuzione: dv, np, pr (development, non-production, production) | |
region | Filtra per una regione Azure (vuoto = tutte le regioni) | |
notes | Note in testo libero (ignorate dal producer) |
Gerarchia dell’output
Modalità singola: salva in microsoft-azure-<timestamp>-<name>.json nella directory corrente.
Modalità multi/batch/all: organizzate per tenant e timestamp:
output/
<TenantID>/
<timestamp>/
<SubscriptionName>.json
Ogni sottoscrizione produce un documento OSIRIS autocontenuto. I riferimenti tra sottoscrizioni (ad esempio VNet peering o connessioni ExpressRoute verso sottoscrizioni remote) vengono emessi come risorse stub con provider.subscription impostato sull’ID della sottoscrizione remota, in modo che l’arco topologico sopravviva al confine mentre il documento rimane valido.
Ambienti multi-tenant
Esegui il producer una volta per tenant. Ogni az login autentica verso un tenant. Usa az login --tenant <tenant-id> per cambiare tenant. La gerarchia di output raggruppa automaticamente i documenti per tenant.
Riferimento dei flag
| Flag | Breve | Descrizione |
|---|---|---|
--subscription | -S | ID della/e sottoscrizione/i Azure, separati da virgole |
--all | Rileva automaticamente tutte le sottoscrizioni accessibili | |
--source | -s | File CSV con le sottoscrizioni di destinazione |
--output | -o | Directory di output (obbligatoria in modalità multi/all/CSV) |
--tenant | ID del tenant Azure AD / Entra ID (opzionale) | |
--region | Filtra per una specifica regione Azure (opzionale) | |
--purpose | Grado di dettaglio dell’output: documentation (predefinito) oppure audit. Vedi Purpose sotto | |
--safe-failure-mode | Gestione dei segreti: fail-closed (predefinito), log-and-redact, off | |
--version / -v | Mostra la versione ed esce | |
--help | Mostra la guida ed esce |
Finalità
Il flag --purpose implementa OSIRIS JSON specification chapter 13.1.3 (data minimization). La raccolta è sempre esaustiva; l’emissione viene modellata in base alla finalità dichiarata, in modo che la stessa esecuzione del producer possa servire sia casi d’uso di visualizzazione leggera sia casi d’uso di audit / conformità.
| Valore | Comportamento |
|---|---|
documentation (predefinito) | Campi minimi: identità, tipo, tracciabilità del provider, nomi, tag e relazioni di alto livello. Le mappe properties ed extensions per risorsa vengono rimosse. Adatto a diagrammi, dashboard di inventario e documentazione di alto livello. |
audit | Tutti i campi leggibili, dopo la redazione dei campi sensibili. Mappe properties ed extensions complete per ogni risorsa, connessione e gruppo. Adatto a revisioni di conformità, audit, drift di configurazione o documentazione approfondita e progettazione accurata della topologia. |
Il valore selezionato viene registrato nel documento sotto metadata.scope.purpose, così i consumatori possono capire quale grado di dettaglio stanno leggendo.
[!IMPORTANT] I segreti vengono sempre redatti indipendentemente dalla finalità. La proiezione
auditaggiunge dettagli (indirizzi IP, regole NSG, sottocampi SKU, dettagli BGP, ecc.); non aggiunge mai materiale di autenticazione. Password amministrative dei database, chiavi di accesso di Cosmos / Redis / Service Bus / Event Hubs, chiavi di strumentazione di App Insights e chiavi condivise di Log Analytics non vengono mai raccolte.
# Predefinito: documentation (proiezione minima)
osirisjson-producer azure -S a1b2c3d4-e5f6-7890-abcd-ef1234567890
# Audit: fedeltà ARM completa
osirisjson-producer azure -S a1b2c3d4-e5f6-7890-abcd-ef1234567890 --purpose audit
Cosa raccoglie il producer OSIRIS JSON per Microsoft Azure
Il producer OSIRIS JSON per Microsoft Azure raccoglie, a ogni esecuzione, un inventario completo dei tipi di risorsa supportati tramite la Azure CLI. La tabella seguente raggruppa gli elementi interrogati.
Rete
| Risorsa Microsoft Azure | Tipo OSIRIS JSON |
|---|---|
| Virtual Networks | network.vpc |
| Subnets | network.subnet |
| Network Interfaces | network.interface |
| Network Security Groups | network.security.group |
| Application Security Groups | osiris.azure.asg |
| Route Tables | osiris.azure.routetable |
| Public IP Addresses | osiris.azure.publicip |
| Load Balancers (L4) | network.loadbalancer |
| Application Gateways (L7) | network.loadbalancer |
| Azure Firewalls | network.firewall |
| NAT Gateways | osiris.azure.gateway.nat |
| VNet Gateways (VPN / ExpressRoute) | osiris.azure.gateway.vnet |
| ExpressRoute Circuits | osiris.azure.expressroute |
| Private Endpoints | osiris.azure.privateendpoint |
| DNS Zones | osiris.azure.dns.zone |
| Private DNS Zones | osiris.azure.dns.privatezone |
Calcolo e storage
| Risorsa Microsoft Azure | Tipo OSIRIS JSON |
|---|---|
| Virtual Machines | compute.vm |
| Managed Disks | osiris.azure.disk |
| Managed Snapshots | osiris.azure.snapshot |
| Storage Accounts | osiris.azure.storageaccount |
App Service / livello web
| Risorsa Microsoft Azure | Tipo OSIRIS JSON |
|---|---|
| App Service Plan | osiris.azure.appserviceplan |
| Web App | osiris.azure.webapp |
| Function App | osiris.azure.functionapp |
Routing di App Service: i siti il cui kind contiene functionapp vengono emessi come osiris.azure.functionapp; tutti gli altri siti vengono emessi come osiris.azure.webapp.
Identità e sicurezza
| Risorsa Microsoft Azure | Tipo OSIRIS JSON |
|---|---|
| Key Vault | osiris.azure.keyvault |
| Container Registry | osiris.azure.containerregistry |
| User-Assigned Managed Identity | osiris.azure.managedidentity |
Backup e disaster recovery
| Risorsa Microsoft Azure | Tipo OSIRIS JSON |
|---|---|
| Recovery Services Vault | osiris.azure.recoveryvault |
| Backup Vault (Azure Backup) | osiris.azure.backupvault |
Database
| Risorsa Microsoft Azure | Tipo OSIRIS JSON |
|---|---|
| SQL Server | osiris.azure.sqlserver |
| SQL Database | osiris.azure.sqldatabase |
| PostgreSQL Flexible Server | osiris.azure.postgresqlserver |
| MySQL Flexible Server | osiris.azure.mysqlserver |
| Cosmos DB account | osiris.azure.cosmosaccount |
| Redis Cache | osiris.azure.redis |
Container e integrazione
| Risorsa Microsoft Azure | Tipo OSIRIS JSON |
|---|---|
| AKS Cluster | osiris.azure.aks.cluster |
| AKS Agent Pool | osiris.azure.aks.nodepool |
| Container App Managed Environment | osiris.azure.containerapp.environment |
| Container App | osiris.azure.containerapp |
| Container Group / ACI | osiris.azure.containergroup |
| Service Bus Namespace | osiris.azure.servicebus.namespace |
| Event Hubs Namespace | osiris.azure.eventhubs.namespace |
| API Management Service | osiris.azure.apim |
| Front Door (Standard / Premium) | osiris.azure.frontdoor.profile |
Osservabilità
| Risorsa Microsoft Azure | Tipo OSIRIS JSON |
|---|---|
| Application Insights | osiris.azure.applicationinsights |
| Log Analytics Workspace | osiris.azure.loganalytics |
Contenimento
| Risorsa Microsoft Azure | Tipo OSIRIS JSON |
|---|---|
| Resource Groups | container.resourcegroup |
Cosa intenzionalmente non viene raccolto
OSIRIS JSON definisce un formato JSON neutrale rispetto ai vendor per descrivere risorse infrastrutturali, le loro proprietà e le loro relazioni topologiche; non è un formato Infrastructure-as-Code o simile. Puoi leggere di più qui: What is OSIRIS JSON. I seguenti elementi sono intenzionalmente fuori ambito:
- Criteri di monitoraggio: alert rules, action groups, metric alerts, scheduled query rules.
- Criteri di backup / retention all’interno di Recovery Services Vault e Backup Vault (i vault e gli archi verso gli elementi protetti vengono emessi; i corpi dei criteri no).
- Criteri del livello database: SQL auditing, threat-detection, TDE, firewall rules, security-alert-policy.
- Criteri, prodotti, operazioni e named values di API Management.
- Route, rule set, endpoint e associazioni di criteri WAF di Front Door (il profilo viene emesso; il routing no).
- Segreti di Container App e variabili d’ambiente ACI.
- Enumerazione dei diagnostic setting per risorsa (aggiungerebbe una chiamata
azper ogni risorsa). - Azure Front Door classico (
Microsoft.Network/frontDoors, deprecato). Microsoft.DBforPostgreSQL/serverslegacy (single server, end-of-life nella roadmap di Azure).
Struttura dell’output OSIRIS JSON per Microsoft Azure
{
"$schema": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
"version": "1.0.0",
"metadata": {
"generator": {
"name": "osirisjson-producer-azure",
"version": "0.4.0",
"url": "https://osirisjson.org"
},
"scope": {
"name": "<subscription-id> - <subscription-name>",
"purpose": "documentation",
"providers": ["azure"],
"accounts": ["<tenant-id>"],
"subscriptions": ["<subscription-id>"],
"regions": ["westeurope", "eastus2"]
}
},
"topology": {
"resources": [ ... ],
"connections": [ ... ],
"groups": [ ... ]
}
}
Tipi di connessione
Gli archi di connessione utilizzano i sottotipi standard di OSIRIS JSON v1.0 come da specification chapter 5.2.3, così i consumatori possono distinguere i livelli della topologia.
| Tipo di connessione OSIRIS JSON | Usato per |
|---|---|
contains | Contenimento (Subnet all’interno della VNet, App Service Plan all’interno del sito, AKS Cluster all’interno del pool di nodi, RG all’interno della Subscription, SQL Server all’interno di SQL Database, source Disk all’interno di Snapshot, VM all’interno del Disk collegato) |
network | Connettività di rete generica (NIC verso subnet, associazioni NSG, link DNS, connessioni gateway, App Insights verso workspace, Web App verso App Insights, AKS / Redis / ACI verso subnet, APIM verso subnet) |
network.peering | VNet peering |
network.vpn | Connessioni VPN gateway |
network.bgp | Connessioni dei circuiti ExpressRoute |
dependency | Private Endpoint verso una destinazione PaaS (Web App, Function App, Key Vault, Container Registry, Recovery Services Vault, cluster AKS, Service Bus, Event Hubs, APIM) |
dependency.storage | Private Endpoint verso Storage Account |
dependency.database | Private Endpoint verso database (SQL Server, Cosmos DB, Redis) |
Tipi di gruppo
| Tipo di gruppo OSIRIS JSON | Usato per |
|---|---|
logical.subscription | Gruppo di sottoscrizione di livello superiore |
logical.resourcegroup | Gruppi di resource group (figli della sottoscrizione) |
container.region | Un gruppo per ogni provider.region distinto osservato nella sottoscrizione, includendo ogni risorsa in quella regione. La regione global e le risorse senza regione vengono saltate (non hanno ambito geografico). Il token di delimitazione è <subscription-id>/<region>, quindi i gruppi non collidono mai tra sottoscrizioni. |
Tipi di risorsa
I tipi di risorsa seguono la OSIRIS JSON v1.0 specification. I tipi standard vengono usati quando definiti; i tipi specifici di Azure usano il namespace osiris.azure.*.
Tipi standard:
container.resourcegroup- Resource groupnetwork.vpc- Virtual networknetwork.subnet- Subnetnetwork.interface- Interfacce di retenetwork.security.group- Network security groupnetwork.loadbalancer- Load balancer (L4 e L7 / Application Gateway)network.firewall- Azure Firewallcompute.vm- Virtual machine
Estensioni (osiris.azure)
I dati specifici di Azure che non mappano su proprietà portabili di OSIRIS JSON vengono emessi sotto il namespace di estensione osiris.azure. Questo segue la specifica di OSIRIS JSON: properties contiene dati comuni / portabili, extensions contiene dati profondi specifici del vendor. Le estensioni vengono emesse solo con --purpose audit.
Le estensioni rappresentative includono:
| Tipo di risorsa OSIRIS JSON | Campi di estensione selezionati |
|---|---|
network.interface | enable_accelerated_networking, effective_routes[] |
network.security.group | security_rules[], default_security_rules[] |
osiris.azure.expressroute | sku, sku_tier, service_provider, peerings[] (tipo di peering BGP, stato, ASN del peer, ID VLAN, prefissi di indirizzo) |
osiris.azure.webapp / osiris.azure.functionapp | managed_identity, outbound_vnet_routing, private_endpoint_connection_ids[], app_insights_id |
osiris.azure.storageaccount / osiris.azure.keyvault / osiris.azure.containerregistry / osiris.azure.recoveryvault / osiris.azure.sqlserver / osiris.azure.cosmosaccount | private_endpoint_connection_ids[] |
osiris.azure.applicationinsights | workspace_resource_id (workspace Log Analytics associato) |
osiris.azure.loganalytics | customer_id (UUID del workspace usato da KQL; non è un segreto) |
Metadati del provider
Ogni risorsa include provider.type con il tipo nativo di risorsa ARM (ad es. Microsoft.Network/virtualNetworks, Microsoft.Compute/virtualMachines). Gli stub tra sottoscrizioni includono provider.subscription con l’ID della sottoscrizione remota. Tutte le risorse includono provider.source impostato a azure-cli.
ID delle risorse
Gli ID delle risorse Azure seguono il pattern azure::<ARM-resource-id>, usando l’intero ARM resource ID come identificatore nativo. Questo garantisce ID globalmente univoci e deterministici, che sopravvivono alla correlazione tra sottoscrizioni.
Canonicalizzazione della regione
provider.region e metadata.scope.regions vengono canonicalizzati nella forma slug di Azure (minuscolo, senza spazi). La CLI az restituisce location in modo incoerente tra i tipi di risorsa: la maggior parte delle risorse ARM usa westeurope / eastus2, mentre App Service Plans e Web Apps espongono la forma di visualizzazione (West Europe). Il producer normalizza alla forma slug in modo che una sottoscrizione a singola regione non appaia come due regioni in metadata.scope.regions.
Requisiti RBAC
| Livello di permesso | Cosa viene raccolto |
|---|---|
| Reader | Tutti i tipi di risorsa, le proprietà e le estensioni (regole NSG, peering ER, connessioni gateway, VNet peering, link DNS, archi da Private Endpoint a destinazioni, App Service verso App Insights, risorse AKS, container, database, messaggistica e osservabilità) |
Reader + effectiveRouteTable/action | Tutto quanto sopra + route effettive della NIC |
| Network Contributor / Owner | Dataset completo senza restrizioni |
Il producer verifica il permesso sulla prima NIC e salta in modo sicuro la raccolta delle route effettive se il permesso viene negato. Tutti gli altri dati vengono raccolti comunque.
Esempi
Sottoscrizione singola
Esploreremo una singola sottoscrizione nel nostro tenant e genereremo da Microsoft Azure un documento OSIRIS JSON.
osirisjson-producer azure -S a1b2c3d4-e5f6-7890-abcd-ef1234567890 --purpose audit
Documento di output OSIRIS JSON (ridotto, --purpose audit):
{
"$schema": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
"version": "1.0.0",
"metadata": {
"generator": {
"name": "osirisjson-producer-azure",
"version": "0.4.0",
"url": "https://osirisjson.org"
},
"scope": {
"name": "a1b2c3d4-e5f6-7890-abcd-ef1234567890 - my-nonprod-subscription",
"purpose": "audit",
"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",
"source": "azure-cli",
"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"],
"subnet_count": 4,
"enable_ddos_protection": false,
"peerings": [
{
"name": "hub-to-spoke",
"peering_state": "Connected",
"remote_vnet_id": "/subscriptions/a1b2c3d4/.../spoke-vnet",
"allow_gateway_transit": true,
"allow_forwarded_traffic": true
}
]
}
},
{
"id": "azure::/subscriptions/a1b2c3d4/resourceGroups/data-rg/providers/Microsoft.Storage/storageAccounts/mystg",
"type": "osiris.azure.storageaccount",
"name": "mystg",
"status": "active",
"provider": {
"name": "azure",
"native_id": "/subscriptions/a1b2c3d4/resourceGroups/data-rg/providers/Microsoft.Storage/storageAccounts/mystg",
"type": "Microsoft.Storage/storageAccounts",
"region": "westeurope",
"source": "azure-cli",
"subscription": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"tenant": "f1e2d3c4-b5a6-9078-fedc-ba9876543210"
},
"properties": {
"resource_group": "data-rg",
"sku_tier": "Standard",
"sku_name": "Standard_LRS",
"kind": "StorageV2",
"access_tier": "Hot",
"https_only": true,
"min_tls_version": "TLS1_2",
"public_network_access": "Disabled",
"allow_blob_public_access": false
},
"extensions": {
"osiris.azure": {
"private_endpoint_connection_ids": [
"/subscriptions/a1b2c3d4/.../privateEndpoints/pe-mystg"
]
}
}
}
],
"connections": [
{
"source": "azure::/subscriptions/a1b2c3d4/.../subnets/default",
"target": "azure::/subscriptions/a1b2c3d4/.../virtualNetworks/hub-vnet",
"type": "contains",
"direction": "forward"
},
{
"source": "azure::/subscriptions/a1b2c3d4/.../privateEndpoints/pe-mystg",
"target": "azure::/subscriptions/a1b2c3d4/.../storageAccounts/mystg",
"type": "dependency.storage",
"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::data-rg"
]
},
{
"id": "azure::region::a1b2c3d4-e5f6-7890-abcd-ef1234567890/westeurope",
"type": "container.region",
"name": "westeurope",
"members": [
"azure::/subscriptions/a1b2c3d4/.../virtualNetworks/hub-vnet",
"azure::/subscriptions/a1b2c3d4/.../storageAccounts/mystg"
]
}
]
}
}
La stessa esecuzione con il valore predefinito --purpose documentation restituisce un grafo di risorse identico, ma con le mappe properties ed extensions rimosse da ogni risorsa, connessione e gruppo, risultando adatto a viste topologiche di alto livello e documentazione.