Produttore OSIRIS JSON per Microsoft Azure

Il produttore OSIRIS JSON per Azure si connette a Microsoft Azure tramite Azure CLI (az) e genera snapshot OSIRIS JSON della topologia della tua sottoscrizione. A partire da v0.5.0, il produttore copre i livelli di rete, calcolo, storage, identità, database, container, integrazione, osservabilità, backup, automazione e gruppi di gestione, includendo le relative dipendenze tra risorse (Private Endpoint verso target PaaS, App Service verso App Insights, Log Analytics, RSV, Backup Vault verso elementi protetti, AKS verso subnet e node pool, ecc.).

Per iniziare a usare OSIRIS JSON per Microsoft Azure, installa il dispatcher principale e il produttore 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 principale consente di eseguire osirisjson-producer azure .... Senza di esso, invoca 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

1. Installa Azure CLI
2. Autenticati: az login
3. L’utente autenticato deve avere il ruolo Reader (o un’autorizzazione di lettura equivalente) sulle sottoscrizioni di destinazione. Per la raccolta completa dei dati, incluse le effective route, l’utente necessita anche dell’autorizzazione Microsoft.Network/networkInterfaces/effectiveRouteTable/action (inclusa in Network Contributor e ruoli superiori). Se questa autorizzazione è assente, il produttore salta la raccolta delle effective route con un log INFO e continua normalmente.

Puoi eseguire il produttore sulla tua macchina locale oppure invocarlo tramite un job schedulato 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 produttore 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 digita all.

Modalità multi-sottoscrizione

Raccogli più sottoscrizioni in una directory di output:

# 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

Modalità batch (CSV)

Genera un template CSV:

osirisjson-producer azure template --generate

Raccogli da un file CSV:

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

Il template CSV usa queste colonne:

Gerarchia di 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 autonomo. I riferimenti tra sottoscrizioni (ad esempio peering VNet o connessioni ExpressRoute verso sottoscrizioni remote) sono emessi come risorse stub con provider.subscription impostato sull’ID della sottoscrizione remota, in modo che l’arco di topologia attraversi il confine mentre il documento resta valido.

Ambienti multi-tenant

Esegui il produttore 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 delle flag

Scopo

La flag --purpose implementa il capitolo 13.1.3 della specifica OSIRIS JSON (minimizzazione dei dati). La raccolta è sempre esaustiva; l’emissione è modellata dallo scopo dichiarato, così la stessa esecuzione del produttore può servire sia casi d’uso di visualizzazione leggera sia casi d’uso di audit / compliance.

Il valore selezionato viene registrato nel documento in metadata.scope.purpose, così i consumer possono capire quale grado di dettaglio stanno leggendo.

[!IMPORTANT] I segreti sono sempre redatti indipendentemente dallo scopo. La proiezione di audit aggiunge dettagli (indirizzi IP, regole NSG, sottocampi SKU, dettagli BGP, ecc.); non aggiunge mai materiale di autenticazione. Password amministrative dei database, chiavi di accesso Cosmos / Redis / Service Bus / Event Hubs, chiavi di strumentazione di App Insights e chiavi condivise di Log Analytics non vengono mai raccolte.

# Default: documentation (minimal projection)
osirisjson-producer azure -S a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Audit: full ARM fidelity
osirisjson-producer azure -S a1b2c3d4-e5f6-7890-abcd-ef1234567890 --purpose audit

Cosa raccoglie il produttore OSIRIS JSON per Microsoft Azure

Il produttore OSIRIS JSON per Microsoft Azure raccoglie a ogni esecuzione un inventario completo dei tipi di risorsa supportati tramite Azure CLI. Le tabelle seguenti raggruppano ciò che viene interrogato.

Rete

Calcolo

Storage

App Service / livello web

Routing di App Service: i siti il cui kind contiene functionapp sono emessi come osiris.azure.functionapp; tutti gli altri siti sono emessi come osiris.azure.webapp.

Identità e sicurezza

Backup e disaster recovery

Database

Container

Integrazione e messaggistica

Automazione e workflow

Osservabilità

Le risorse Metric Alert e Action Group sono limitate a --purpose audit perché sono costrutti di policy di osservabilità, non risorse di topologia; con lo scopo predefinito documentation non vengono emesse.

Contenimento

Cosa non viene raccolto intenzionalmente

OSIRIS JSON definisce un formato JSON vendor-neutral per descrivere risorse infrastrutturali, le loro proprietà e le loro relazioni topologiche - non è un formato Infrastructure-as-Code o simile. Puoi approfondire qui: Cos’è OSIRIS JSON. I seguenti elementi sono intenzionalmente fuori ambito:

• Policy di backup / retention sotto Recovery Services Vault e Backup Vault (i vault e gli archi verso gli elementi protetti sono emessi; i corpi delle policy no).
• Policy del livello database: auditing SQL, threat-detection, TDE, regole firewall, security-alert-policy.
• Policy, prodotti, operazioni e named value di API Management.
• Route, rule set, endpoint e associazioni di policy WAF di Front Door (il profilo viene emesso; il routing no).
• Segreti di Container App e variabili di ambiente ACI.
• Enumerazione dei diagnostic setting per risorsa (aggiungerebbe una chiamata az per risorsa).
• Azure Front Door classico (Microsoft.Network/frontDoors, deprecato).
• Microsoft.DBforPostgreSQL/servers legacy (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.5.0",
      "url": "https://osirisjson.org/en/docs/producers/hyperscalers/microsoft-azure"
    },
    "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 usano i sottotipi standard di OSIRIS JSON v1.0 secondo il capitolo 5.2.3 della specifica, così i consumer possono distinguere i livelli della topologia.

Tipi di gruppo

Tipi di risorsa

I tipi di risorsa seguono la specifica OSIRIS JSON v1.0. I tipi standard sono usati dove definiti; i tipi specifici di Azure usano il namespace osiris.azure.*.

Tipi standard:

• container.resourcegroup - Gruppi di risorse
• network.vpc - Reti virtuali
• network.subnet - Subnet
• network.interface - Interfacce di rete
• network.security.group - Network security group
• network.loadbalancer - Load balancer (solo L4; gli Application Gateway usano osiris.azure.applicationgateway)
• network.firewall - Azure Firewalls
• compute.vm - Macchine virtuali

Estensioni (osiris.azure)

I dati specifici di Azure che non mappano a proprietà OSIRIS JSON portabili sono emessi sotto il namespace di estensione osiris.azure. Questo segue la specifica OSIRIS JSON: properties contiene dati comuni / portabili, extensions contiene dati approfonditi specifici del vendor. Le estensioni sono emesse solo con --purpose audit.

Le estensioni rappresentative includono:

[!NOTE] network.security.group security_rules[] (regole definite dall’utente) sono emesse in properties, non in extensions, perché sono un segnale primario di topologia. Solo default_security_rules[] (regole baseline gestite da Azure) va in extensions.

Anche network.interface private_ip viene emesso in properties per lo stesso motivo.

Metadati del provider

Ogni risorsa include provider.type con il tipo di risorsa ARM nativo (ad esempio 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’ID risorsa ARM completo come identificatore nativo. Questo garantisce ID globalmente univoci e deterministici che sopravvivono alla correlazione tra sottoscrizioni.

Canonicalizzazione delle regioni

provider.region e metadata.scope.regions sono canonicalizzati nella forma slug di Azure (minuscolo, senza spazi). La CLI az restituisce location in modo non uniforme tra i tipi di risorsa: la maggior parte delle risorse ARM usa westeurope / eastus2, mentre App Service Plan e Web App espongono la forma di visualizzazione (West Europe). Il produttore normalizza allo slug in modo che una sottoscrizione a singola regione non appaia come due regioni in metadata.scope.regions.

Requisiti RBAC

Il produttore verifica l’autorizzazione sulla prima NIC e salta in modo controllato la raccolta delle effective route se l’autorizzazione viene negata. 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.5.0",
      "url": "https://osirisjson.org/en/docs/producers/hyperscalers/microsoft-azure"
    },
    "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.storage",
        "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"
        ],
        "extensions": {
          "osiris.azure": {
            "management_group_path": ["Tenant Root Group", "Corp", "NonProd"]
          }
        }
      },
      {
        "id": "azure::managementgroup::NonProd",
        "type": "logical.managementgroup",
        "name": "NonProd",
        "children": [
          "azure::subscription::a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        ]
      },
      {
        "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 il grafo delle risorse identico, ma con le mappe properties ed extensions rimosse da ogni risorsa, connessione e gruppo, rendendolo adatto a viste topologiche di alto livello e documentazione.