Productor OSIRIS JSON para Microsoft Azure

El productor Azure de OSIRIS JSON se conecta a Microsoft Azure mediante Azure CLI (az) y genera instantáneas OSIRIS JSON de la topología de sus suscripciones. A partir de v0.4.0, el productor cubre las capas de red, cómputo, almacenamiento, identidad, bases de datos, contenedores, integración, observabilidad y respaldo, incluyendo sus aristas de dependencia entre recursos (Private Endpoint hacia destinos PaaS, App Service hacia App Insights, Log Analytics, RSV, Backup Vault hacia elementos protegidos, AKS hacia subredes y pools de nodos, etc.).

Para empezar a usar OSIRIS JSON para Microsoft Azure, instale el dispatcher principal y el productor OSIRIS JSON para Microsoft Azure:

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

El dispatcher principal le permite ejecutar osirisjson-producer azure .... Sin él, invoque directamente el binario del proveedor como osirisjson-producer-azure ....

Asegúrese de que $GOPATH/bin (o $HOME/go/bin) esté en su PATH. Consulte la página getting started para ver más opciones de instalación.

Requisitos previos

1. Instale la Azure CLI
2. Autentíquese: az login
3. El usuario autenticado debe tener el rol Reader (o un permiso de lectura equivalente) en la o las suscripciones de destino. Para la recopilación completa de datos, incluyendo rutas efectivas, el usuario también necesita el permiso Microsoft.Network/networkInterfaces/effectiveRouteTable/action (incluido en Network Contributor y superiores). Si este permiso no está presente, el productor omite la recopilación de rutas efectivas con un registro INFO y continúa normalmente.

Puede ejecutar el productor en su máquina local o invocarlo mediante un trabajo programado con una cuenta de servicio en la plataforma de su preferencia.

Uso de la CLI

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

Modo único

Empiece recopilando una suscripción, que se guardará automáticamente como microsoft-azure-<timestamp>-<name>.json:

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

Modo interactivo

Ejecute sin flags para obtener un selector interactivo de suscripciones:

osirisjson-producer azure

El productor detecta todas las suscripciones accesibles y presenta una lista numerada. Seleccione usando números individuales (1,3,5), rangos (30-55), combinaciones (1,3,30-55) o escriba all.

Modo multi-suscripción

Recopile varias suscripciones en un directorio de salida:

# Suscripciones específicas
osirisjson-producer azure -S sub-id-1,sub-id-2,sub-id-3 -o ./output

# Todas las suscripciones accesibles (descubrimiento automático)
osirisjson-producer azure --all -o ./output

# Todas las suscripciones de un tenant específico
osirisjson-producer azure --all --tenant f1e2d3c4-b5a6-9078-fedc-ba9876543210 -o ./output

Modo por lotes (CSV)

Genere una plantilla CSV:

osirisjson-producer azure template --generate

Recopile a partir de un archivo CSV:

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

La plantilla CSV utiliza estas columnas:

Jerarquía de salida

Modo único: guarda en microsoft-azure-<timestamp>-<name>.json en el directorio actual.

Modos multi/por lotes/todas las suscripciones: organizados por tenant y marca de tiempo:

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

Cada suscripción produce un documento OSIRIS autocontenido. Las referencias entre suscripciones (por ejemplo, peerings de VNet o conexiones ExpressRoute hacia suscripciones remotas) se emiten como recursos stub con provider.subscription establecido en el ID de la suscripción remota, de modo que la arista topológica sobreviva al límite mientras el documento siga siendo válido.

Entornos multi-tenant

Ejecute el productor una vez por tenant. Cada az login autentica contra un tenant. Use az login --tenant <tenant-id> para cambiar. La jerarquía de salida agrupa los documentos por tenant automáticamente.

Referencia de flags

Propósito

La opción --purpose implementa OSIRIS JSON specification chapter 13.1.3 (data minimization). La recopilación siempre es exhaustiva; la emisión se moldea según el propósito declarado, de manera que la misma ejecución del productor pueda servir tanto para casos de uso de visualización ligera como para casos de uso de auditoría / cumplimiento.

El valor seleccionado se registra en el documento bajo metadata.scope.purpose, para que los consumidores puedan saber qué nivel de detalle están leyendo.

[!IMPORTANT] Los secretos siempre se redactan sin importar el propósito. La proyección de auditoría agrega detalles (direcciones IP, reglas NSG, subcampos de SKU, detalles de BGP, etc.); nunca agrega material de autenticación. Las contraseñas de administrador de base de datos, las claves de acceso de Cosmos / Redis / Service Bus / Event Hubs, las claves de instrumentación de App Insights y las claves compartidas de Log Analytics nunca se recopilan.

# Predeterminado: documentation (proyección mínima)
osirisjson-producer azure -S a1b2c3d4-e5f6-7890-abcd-ef1234567890

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

Qué recopila el productor OSIRIS JSON para Microsoft Azure

El productor OSIRIS JSON para Microsoft Azure recopila un inventario completo de los tipos de recursos compatibles mediante Azure CLI en cada ejecución. La siguiente tabla agrupa lo que se consulta.

Redes

Cómputo y almacenamiento

App Service / capa web

Enrutamiento de App Service: los sitios cuyo kind contiene functionapp se emiten como osiris.azure.functionapp; todos los demás sitios se emiten como osiris.azure.webapp.

Identidad y seguridad

Respaldo y recuperación ante desastres

Bases de datos

Contenedores e integración

Observabilidad

Contención

Qué no se recopila intencionalmente

OSIRIS JSON define un formato JSON neutral respecto del proveedor para describir recursos de infraestructura, sus propiedades y sus relaciones topológicas; no es un formato de Infrastructure-as-Code ni algo similar. Puede leer más aquí: What is OSIRIS JSON. Lo siguiente queda intencionalmente fuera de alcance:

• Política de monitoreo: alert rules, action groups, metric alerts, scheduled query rules.
• Políticas de respaldo / retención dentro de Recovery Services Vault y Backup Vault (los vaults y las aristas hacia elementos protegidos se emiten; los cuerpos de las políticas no).
• Políticas de la capa de base de datos: SQL auditing, threat-detection, TDE, firewall rules, security-alert-policy.
• Políticas, productos, operaciones y named values de API Management.
• Rutas de Front Door, rule sets, endpoints y asociaciones de políticas WAF (el perfil se emite; el enrutamiento no).
• Secretos de Container App y variables de entorno de ACI.
• Enumeración de diagnostic settings por recurso (agregaría una llamada az por recurso).
• Azure Front Door clásico (Microsoft.Network/frontDoors, obsoleto).
• Microsoft.DBforPostgreSQL/servers heredado (servidor único, en fin de vida en la hoja de ruta de Azure).

Estructura de salida de OSIRIS JSON para 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": [ ... ]
  }
}

Tipos de conexión

Las aristas de conexión usan los subtipos estándar de OSIRIS JSON v1.0 según specification chapter 5.2.3, para que los consumidores puedan distinguir las capas de la topología.

Tipos de grupo

Tipos de recurso

Los tipos de recurso siguen la OSIRIS JSON v1.0 specification. Los tipos estándar se usan cuando están definidos; los tipos específicos de Azure usan el namespace osiris.azure.*.

Tipos estándar:

• container.resourcegroup - Grupos de recursos
• network.vpc - Redes virtuales
• network.subnet - Subredes
• network.interface - Interfaces de red
• network.security.group - Grupos de seguridad de red
• network.loadbalancer - Balanceadores de carga (L4 y L7 / Application Gateway)
• network.firewall - Firewalls de Azure
• compute.vm - Máquinas virtuales

Extensiones (osiris.azure)

Los datos específicos de Azure que no se mapean a propiedades portables de OSIRIS JSON se emiten bajo el namespace de extensión osiris.azure. Esto sigue la especificación de OSIRIS JSON: properties contiene datos comunes / portables, extensions contiene datos profundos específicos del proveedor. Las extensiones solo se emiten con --purpose audit.

Las extensiones representativas incluyen:

Metadatos del proveedor

Cada recurso incluye provider.type con el tipo de recurso ARM nativo (por ejemplo, Microsoft.Network/virtualNetworks, Microsoft.Compute/virtualMachines). Los stubs entre suscripciones incluyen provider.subscription con el ID de la suscripción remota. Todos los recursos incluyen provider.source establecido en azure-cli.

ID de recursos

Los ID de recursos de Azure siguen el patrón azure::<ARM-resource-id>, utilizando el ID completo del recurso ARM como identificador nativo. Esto garantiza ID globalmente únicos y determinísticos que sobreviven a la correlación entre suscripciones.

Canonicalización de región

provider.region y metadata.scope.regions se canonicalizan a la forma slug de Azure (minúsculas, sin espacios). La CLI az devuelve location de forma inconsistente entre tipos de recurso: la mayoría de los recursos ARM usan westeurope / eastus2, mientras que los App Service Plans y Web Apps muestran la forma de visualización (West Europe). El productor normaliza al slug para que una suscripción de una sola región no aparezca como dos regiones en metadata.scope.regions.

Requisitos de RBAC

El productor prueba el permiso en la primera NIC y omite de forma segura la recopilación de rutas efectivas si el permiso es denegado. Todos los demás datos se recopilan sin importar eso.

Ejemplos

Suscripción individual

Vamos a explorar una sola suscripción en nuestro tenant y generar desde Microsoft Azure un documento OSIRIS JSON.

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

Documento de salida OSIRIS JSON (recortado, --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 misma ejecución con el valor predeterminado --purpose documentation devuelve el mismo grafo de recursos, pero con los objetos properties y extensions eliminados de cada recurso, conexión y grupo, lo que lo hace adecuado para vistas topológicas de alto nivel y documentación.