Produtor OSIRIS JSON para Microsoft Azure

O produtor Azure do OSIRIS JSON conecta-se ao Microsoft Azure por meio da Azure CLI (az) e gera snapshots OSIRIS JSON da topologia das suas assinaturas. A partir da versão v0.4.0, o produtor cobre as camadas de rede, computação, armazenamento, identidade, bancos de dados, contêineres, integração, observabilidade e backup, incluindo suas arestas de dependência entre recursos (Private Endpoint para alvos PaaS, App Service para App Insights, Log Analytics, RSV, Backup Vault para itens protegidos, AKS para sub-redes e pools de nós etc.).

Para começar a usar o OSIRIS JSON no Microsoft Azure, instale o dispatcher principal e o produtor OSIRIS JSON do Microsoft Azure:

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

O dispatcher principal permite executar osirisjson-producer azure .... Sem ele, invoque diretamente o binário do fornecedor como osirisjson-producer-azure ....

Certifique-se de que $GOPATH/bin (ou $HOME/go/bin) esteja no seu PATH. Consulte a página primeiros passos para mais opções de instalação.

Pré-requisitos

1. Instale a Azure CLI
2. Autentique-se: az login
3. O usuário autenticado deve ter a função Reader (ou permissão equivalente de leitura) na(s) assinatura(s) de destino. Para a coleta completa de dados, incluindo rotas efetivas, o usuário também precisa da permissão Microsoft.Network/networkInterfaces/effectiveRouteTable/action (incluída em Network Contributor e superiores). Se essa permissão estiver ausente, o produtor ignorará a coleta de rotas efetivas, registrará um log INFO e continuará normalmente.

Você pode executar o produtor na sua máquina local ou invocá-lo por meio de um job agendado com uma conta de serviço na plataforma de sua preferência.

Uso da CLI

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

Modo único

Comece coletando uma assinatura, que será salva automaticamente como microsoft-azure-<timestamp>-<name>.json:

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

Modo interativo

Execute sem flags para obter um seletor interativo de assinaturas:

osirisjson-producer azure

O produtor descobre todas as assinaturas acessíveis e apresenta uma lista numerada. Selecione usando números individuais (1,3,5), intervalos (30-55), combinações (1,3,30-55) ou digitando all.

Modo de múltiplas assinaturas

Colete várias assinaturas em um diretório de saída:

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

# Todas as assinaturas acessíveis (descoberta automática)
osirisjson-producer azure --all -o ./output

# Todas as assinaturas em um tenant específico
osirisjson-producer azure --all --tenant f1e2d3c4-b5a6-9078-fedc-ba9876543210 -o ./output

Modo em lote (CSV)

Gere um modelo CSV:

osirisjson-producer azure template --generate

Colete a partir de um arquivo CSV:

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

O modelo CSV usa estas colunas:

Hierarquia de saída

Modo único: salva em microsoft-azure-<timestamp>-<name>.json no diretório atual.

Modos múltiplo/lote/todas: organizados por tenant e timestamp:

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

Cada assinatura produz um documento OSIRIS autocontido. Referências entre assinaturas (por exemplo, peerings de VNet ou conexões ExpressRoute para assinaturas remotas) são emitidas como recursos stub com provider.subscription definido como o ID da assinatura remota, para que a aresta de topologia sobreviva ao limite enquanto o documento permanece válido.

Ambientes multi-tenant

Execute o produtor uma vez por tenant. Cada az login autentica em um tenant. Use az login --tenant <tenant-id> para alternar. A hierarquia de saída agrupa os documentos por tenant automaticamente.

Referência de flags

Finalidade

A flag --purpose implementa o capítulo 13.1.3 da especificação OSIRIS JSON (minimização de dados). A coleta é sempre exaustiva; a emissão é moldada pela finalidade declarada, para que a mesma execução do produtor possa atender tanto a casos de uso de visualização leve quanto a casos de uso de auditoria e conformidade.

O valor selecionado é registrado no documento em metadata.scope.purpose, para que os consumidores possam identificar qual grau de detalhe estão lendo.

[!IMPORTANT] Os segredos são sempre redigidos independentemente da finalidade. A projeção de auditoria adiciona detalhes (endereços IP, regras de NSG, subcampos de SKU, detalhes de BGP etc.); ela nunca adiciona material de autenticação. Senhas de administrador de banco de dados, chaves de acesso do Cosmos / Redis / Service Bus / Event Hubs, chaves de instrumentação do App Insights e chaves compartilhadas do Log Analytics nunca são coletadas.

# Padrão: documentation (projeção mínima)
osirisjson-producer azure -S a1b2c3d4-e5f6-7890-abcd-ef1234567890

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

O que o produtor OSIRIS JSON para Microsoft Azure coleta

O produtor OSIRIS JSON para Microsoft Azure coleta um inventário completo dos tipos de recursos compatíveis por meio da Azure CLI em cada execução. A tabela a seguir agrupa o que é consultado.

Rede

Computação e armazenamento

App Service / camada web

Roteamento do App Service: sites cujo kind contém functionapp são emitidos como osiris.azure.functionapp; todos os demais sites são emitidos como osiris.azure.webapp.

Identidade e segurança

Backup e recuperação de desastres

Bancos de dados

Contêineres e integração

Observabilidade

Contenção

O que intencionalmente não é coletado

O OSIRIS JSON define um formato JSON neutro em relação a fornecedores para descrever recursos de infraestrutura, suas propriedades e suas relações topológicas; não é um formato de Infrastructure-as-Code nem similar. Você pode ler mais aqui: O que é o OSIRIS JSON. Os itens a seguir estão intencionalmente fora de escopo:

• Política de monitoramento: alert rules, action groups, metric alerts, scheduled query rules.
• Políticas de backup / retenção dentro de Recovery Services Vault e Backup Vault (os vaults e as arestas de itens protegidos são emitidos; os corpos das políticas não).
• Política da camada de banco de dados: SQL auditing, threat-detection, TDE, firewall rules, security-alert-policy.
• Políticas, produtos, operações e named values do API Management.
• Rotas do Front Door, conjuntos de regras, endpoints e associações de política WAF (o perfil é emitido; o roteamento não).
• Segredos do Container App e variáveis de ambiente do ACI.
• Enumeração de diagnostic settings por recurso (adicionaria uma chamada az por recurso).
• Azure Front Door clássico (Microsoft.Network/frontDoors, obsoleto).
• Microsoft.DBforPostgreSQL/servers legado (single server, em fim de vida no roadmap do Azure).

Estrutura de saída do 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 conexão

As arestas de conexão usam os subtipos padrão do OSIRIS JSON v1.0 conforme o capítulo 5.2.3 da especificação, para que os consumidores possam distinguir as camadas da topologia.

Tipos de grupo

Tipos de recurso

Os tipos de recurso seguem a especificação OSIRIS JSON v1.0. Os tipos padrão são usados quando definidos; tipos específicos do Azure usam o namespace osiris.azure.*.

Tipos padrão:

• container.resourcegroup - Grupos de recursos
• network.vpc - Redes virtuais
• network.subnet - Sub-redes
• network.interface - Interfaces de rede
• network.security.group - Grupos de segurança de rede
• network.loadbalancer - Balanceadores de carga (L4 e L7 / Application Gateway)
• network.firewall - Azure Firewalls
• compute.vm - Máquinas virtuais

Extensões (osiris.azure)

Dados específicos do Azure que não mapeiam para propriedades portáveis do OSIRIS JSON são emitidos sob o namespace de extensão osiris.azure. Isso segue a especificação do OSIRIS JSON: properties contém dados comuns / portáveis, extensions contém dados específicos e profundos do fornecedor. As extensões só são emitidas com --purpose audit.

As extensões representativas incluem:

Metadados do provedor

Todo recurso inclui provider.type com o tipo nativo de recurso ARM (por exemplo, Microsoft.Network/virtualNetworks, Microsoft.Compute/virtualMachines). Stubs entre assinaturas incluem provider.subscription com o ID da assinatura remota. Todos os recursos incluem provider.source definido como azure-cli.

IDs de recurso

Os IDs de recurso do Azure seguem o padrão azure::<ARM-resource-id>, usando o ID completo do recurso ARM como identificador nativo. Isso garante IDs globalmente únicos e determinísticos, que sobrevivem à correlação entre assinaturas.

Canonicalização de região

provider.region e metadata.scope.regions são canonicalizados para a forma slug do Azure (minúsculas, sem espaços). A CLI az retorna location de forma inconsistente entre os tipos de recurso: a maioria dos recursos ARM usa westeurope / eastus2, enquanto App Service Plans e Web Apps expõem a forma de exibição (West Europe). O produtor normaliza para o slug para que uma assinatura de região única não apareça como duas regiões em metadata.scope.regions.

Requisitos de RBAC

O produtor testa a permissão na primeira NIC e ignora a coleta de rotas efetivas de forma elegante se a permissão for negada. Todos os demais dados são coletados independentemente disso.

Exemplos

Assinatura única

Vamos explorar uma única assinatura em nosso tenant e gerar, a partir do Microsoft Azure, um documento OSIRIS JSON.

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

Documento de saída do OSIRIS JSON (resumido, --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"
        ]
      }
    ]
  }
}

A mesma execução com o padrão --purpose documentation retorna o mesmo grafo de recursos, mas com os mapas properties e extensions removidos de cada recurso, conexão e grupo, tornando-o adequado para visualizações de topologia de alto nível e documentação.