InSpec Azure 资源创建指南：从零开始构建自定义资源

概述

在 InSpec Azure 项目中，创建自定义资源是扩展其功能以满足特定云安全合规需求的关键步骤。本文将深入讲解如何为 Azure 资源创建单数（singular）和复数（plural）形式的 InSpec 资源，帮助开发者掌握资源创建的核心逻辑和最佳实践。

资源类型基础概念

在 InSpec Azure 中，每种资源类型通常需要创建两种形式：

1. 单数资源：用于测试特定资源的详细属性
2. 复数资源：用于测试资源集合的通用特性

以 Azure Key Vault 为例，我们将创建：

• azure_key_vault（单数资源）
• azure_key_vaults（复数资源）

单数资源创建详解

1. 初始化逻辑

创建单数资源前，需要理解其与 Azure REST API 的交互方式：

1. API 端点分析：

   • 典型格式：/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.KeyVault/vaults/{vaultName}?api-version=2019-09-01
   • 其中动态部分需要开发者处理

2. 参数来源：

   • 环境变量：subscriptionId 自动从环境获取
   • 用户提供：
     • resource_group（必需，除非提供 resource_id）
     • name（资源名称，必需）
     • api_version（可选）
     • resource_id（完整资源路径，可选）

2. 资源文件创建步骤

1. 基础结构搭建：

   require 'azure_generic_resource'
   
   class AzureKeyVault < AzureGenericResource
     name 'azure_key_vault'
     desc 'Verifies settings and configuration for an Azure Key Vault'
     example <<-EXAMPLE
       describe azure_key_vault(resource_group: 'rg-1', name: 'vault-1') do
         it { should exist }
         its('name') { should eq('vault-1') }
       end
     EXAMPLE
   

2. 初始化方法实现：

   def initialize(opts = {})
     raise ArgumentError, 'Parameters must be provided in an Hash object.' unless opts.is_a?(Hash)
     
     opts[:resource_provider] = specific_resource_constraint('Microsoft.KeyVault/vaults', opts)
     super(opts, true)
   end
   

3. 字符串表示方法：

   def to_s
     super(AzureKeyVault)
   end
   

3. 高级特性实现

资源标识符扩展

除了默认的 name 参数，可以定义更具体的标识符：

opts[:resource_identifiers] = %i(vault_name)

这样用户既可以使用 name 也可以使用 vault_name 作为参数。

附加资源属性

通过 additional_resource_properties 方法扩展资源属性：

def diagnostic_settings
  return unless exists?
  additional_resource_properties(
    {
      property_name: 'diagnostic_settings',
      property_endpoint: id + '/providers/microsoft.insights/diagnosticSettings',
      api_version: @opts[:diagnostic_settings_api_version],
    }
  )
end

属性后处理

如需对原始数据进行处理后再暴露给用户：

def diagnostic_settings_names
  return unless exists?
  diagnostic_settings unless respond_to?(:diagnostic_settings)
  diagnostic_settings.map { |setting| setting.name }
end

允许自定义参数

通过 allowed_parameters 接受额外参数：

opts[:allowed_parameters] = %i(diagnostic_settings_api_version)
opts[:diagnostic_settings_api_version] ||= 'latest'

复数资源创建指南

1. 初始化逻辑差异

复数资源主要区别在于：

• API 端点支持两种形式：
  • 订阅级别：/subscriptions/{subscriptionId}/providers/Microsoft.KeyVault/vaults
  • 资源组级别：/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.KeyVault/vaults
• resource_group 参数变为可选

2. 资源文件实现

基础结构与单数资源类似，但需注意：

class AzureKeyVaults < AzureGenericResources
  name 'azure_key_vaults'
  desc 'Verifies settings for a collection of Azure Key Vaults'
  
  def initialize(opts = {})
    opts[:resource_provider] = specific_resource_constraint('Microsoft.KeyVault/vaults', opts)
    super(opts)
  end
end

3. FilterTable 数据处理

复数资源通常需要实现 FilterTable 以便筛选：

table do
  column :names, field: 'name'
  column :locations, field: 'location'
  # 添加其他需要筛选的列
end

特殊场景处理

嵌套资源实现

对于存在于其他资源内部的资源（如子网位于虚拟网络中）：

1. 必需参数：需要父资源标识符
2. 资源路径：正确构建嵌套路径

无资源组的资源

某些全局资源（如 Azure AD 资源）没有资源组概念，需要：

• 特殊处理资源 URI
• 调整参数验证逻辑

最佳实践建议

1. 参数命名一致性：保持与 Azure REST API 一致的命名习惯
2. 错误处理：提供清晰的参数验证错误信息
3. 性能考量：避免在属性方法中重复调用 API
4. 文档完整性：为每个资源提供完整的示例和描述

测试与验证

创建资源后，建议：

1. 编写完整的控制测试用例
2. 验证各种参数组合下的行为
3. 检查错误处理场景

通过遵循本指南，开发者可以系统地创建符合 InSpec Azure 标准的自定义资源，有效扩展框架的 Azure 云安全检测能力。