Productor OSIRIS JSON para Microsoft Azure

El productor OSIRIS JSON para Azure se conecta a Microsoft Azure mediante Azure CLI (az) y genera snapshots OSIRIS JSON de la topología de tu suscripción. A partir de v0.5.0, el productor cubre redes, computación, almacenamiento, identidad, bases de datos, contenedores, integración, observabilidad, backup, automatización y niveles de grupos de administración, incluidas 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, instala 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 permite ejecutar osirisjson-producer azure .... Sin él, invoca directamente el binario del proveedor como osirisjson-producer-azure ....

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

Requisitos previos

1. Instala Azure CLI
2. Autentícate: az login
3. El usuario autenticado debe tener el rol Reader (o permiso de lectura equivalente) en las suscripciones de destino. Para la recopilación completa de datos, incluidas las 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 log INFO y continúa normalmente.

Puedes ejecutar el productor en tu máquina local o invocarlo mediante un job programado con una cuenta de servicio en tu plataforma preferida.

Uso de la CLI

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

Modo único

Empieza 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

Ejecuta sin flags para obtener un selector interactivo de suscripciones:

osirisjson-producer azure

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

Modo multisuscripción

Recopila varias suscripciones en un directorio de salida:

# 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

Modo batch (CSV)

Genera una plantilla CSV:

osirisjson-producer azure template --generate

Recopila desde un archivo CSV:

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

La plantilla CSV usa estas columnas:

Jerarquía de salida

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

Modos multi/batch/all: organizados por tenant y timestamp:

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 de topología sobreviva al límite mientras el documento sigue siendo válido.

Entornos multi-tenant

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

Referencia de flags

Propósito

La flag --purpose implementa el capítulo 13.1.3 de la especificación OSIRIS JSON (minimización de datos). La recopilación siempre es exhaustiva; la emisión se ajusta al propósito declarado para que la misma ejecución del productor pueda servir tanto a casos de uso de visualización ligera como a casos de uso de auditoría / cumplimiento.

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

[!IMPORTANT] Los secretos siempre se redactan independientemente del propósito. La proyección de auditoría añade detalles (direcciones IP, reglas NSG, subcampos SKU, detalles BGP, etc.); nunca añade 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.

# 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

Qué recopila el productor OSIRIS JSON para Microsoft Azure

El productor OSIRIS JSON para Microsoft Azure recopila en cada ejecución un inventario completo de los tipos de recurso compatibles mediante Azure CLI. Las tablas siguientes agrupan lo que se consulta.

Red

Computación

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

Backup y recuperación ante desastres

Bases de datos

Contenedores

Integración y mensajería

Automatización y workflows

Observabilidad

Los recursos Metric Alert y Action Group están restringidos a --purpose audit porque son construcciones de política de observabilidad, no recursos de topología; con el propósito predeterminado documentation no se emiten.

Contención

Qué no se recopila intencionadamente

OSIRIS JSON define un formato JSON neutral respecto al proveedor para describir recursos de infraestructura, sus propiedades y sus relaciones topológicas - no es un formato Infrastructure-as-Code ni similar. Puedes leer más aquí: Qué es OSIRIS JSON. Lo siguiente está intencionadamente fuera de alcance:

• Políticas de backup / retención bajo Recovery Services Vault y Backup Vault (se emiten los vaults y las aristas hacia elementos protegidos; los cuerpos de las políticas no).
• Política de capa de base de datos: auditoría SQL, detección de amenazas, TDE, reglas de firewall, security-alert-policy.
• Políticas, productos, operaciones y valores con nombre de API Management.
• Rutas, rule sets, endpoints y asociaciones de políticas WAF de Front Door (se emite el perfil; el enrutamiento no).
• Secretos de Container App y variables de entorno de ACI.
• Enumeración de diagnostic settings por recurso (añadiría una llamada az por recurso).
• Azure Front Door clásico (Microsoft.Network/frontDoors, en desuso).
• Microsoft.DBforPostgreSQL/servers heredado (single server, fin de vida en la roadmap de Azure).

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

Tipos de conexión

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

Tipos de grupo

Tipos de recurso

Los tipos de recurso siguen la especificación OSIRIS JSON v1.0. Se usan tipos estándar donde 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 - Network security groups
• network.loadbalancer - Load balancers (solo L4; Application Gateways usa osiris.azure.applicationgateway)
• network.firewall - Azure Firewalls
• compute.vm - Máquinas virtuales

Extensiones (osiris.azure)

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

Las extensiones representativas incluyen:

[!NOTE] network.security.group security_rules[] (reglas definidas por el usuario) se emiten en properties, no en extensions, porque son una señal primaria de topología. Solo default_security_rules[] (reglas baseline administradas por Azure) van a extensions.

network.interface private_ip también se emite en properties por el mismo motivo.

Metadatos del provider

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.

IDs de recurso

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

Canonicalización de regiones

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 App Service Plans y Web Apps exponen 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 controlada la recopilación de rutas efectivas si el permiso se deniega. Todos los demás datos se recopilan igualmente.

Ejemplos

Suscripción única

Vamos a explorar una única 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.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 misma ejecución con el valor predeterminado --purpose documentation devuelve el grafo de recursos idéntico, pero con los mapas properties y extensions eliminados de cada recurso, conexión y grupo, por lo que resulta adecuado para vistas de topología de alto nivel y documentación.