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

1. Installa la Azure CLI
2. Autenticati: az login
3. 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:

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

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à.

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 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 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

Calcolo e storage

App Service / livello web

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

Backup e disaster recovery

Database

Container e integrazione

Osservabilità

Contenimento

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 az per ogni 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.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.

Tipi di gruppo

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 group
• network.vpc - Virtual network
• network.subnet - Subnet
• network.interface - Interfacce di rete
• network.security.group - Network security group
• network.loadbalancer - Load balancer (L4 e L7 / Application Gateway)
• network.firewall - Azure Firewall
• compute.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:

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

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.