自訂函數規則定義和運行原理 - Cloud Config

當您基於Function Compute建立自訂規則時，如果規則被觸發，配置審計會運行規則對應的函數對資源進行檢測，並提供資源合規評估結果。本文通過Python樣本為您介紹函數規則的函數代碼和函數入參。

什麼是自訂函數規則

自訂函數規則是配置審計通過Function Compute服務的函數來承載規則代碼的自訂規則。

應用情境

當配置審計預置的規則模板和條件規則均不能滿足檢測資源合規性的需求時，您可以通過編寫函數代碼，完成複雜情境的合規檢測。更多情境和程式碼範例，請參見自訂函數規則樣本庫。

運行原理

基於Function Compute建立自訂規則的運行原理如下圖所示。

基於Function Compute建立自訂規則運行原理的說明如下：

在Function Compute中建立函數。
在配置審計中基於Function Compute建立自訂規則，並自動觸發評估。
說明
當您建立規則後，配置審計會自動觸發一次評估。
配置審計通過配置審計服務關聯角色（AliyunServiceRoleForConfig）擷取GetFunction和InvokeFunction介面的許可權。
配置審計調用InvokeFunction介面執行函數，擷取資源配置和規則資訊。
函數執行對資源的評估。
Function Compute通過PutEvaluations介面將資源評估結果返回給配置審計。
配置審計對資源評估結果進行儲存並在控制台展示，以便查看。您還可以對不合規資源進行修正，或設定將資源資料投遞到對應雲端服務。

函數代碼

規則的本質是一段邏輯判斷代碼，這段代碼存放在建立的函數中。在配置審計對資源的持續審計中，通過觸發該函數的執行來實現對資源的評估。本函數代碼主要有兩個函數，具體如下：

handler
handler為入口函數，即自訂規則觸發時調用的函數。當您在Function Compute控制台上建立函數時，需要設定Handler。關於Handler的更多資訊，請參見請求處理常式（Handler）。
說明
配置審計僅支援事件請求處理常式（Event Handler）。
put_evaluations
通過PutEvaluations介面將資源評估結果返回給配置審計。

函數代碼的Python樣本如下：

# # !/usr/bin/env python
# # -*- encoding: utf-8 -*-
import json
import logging

from aliyunsdkcore.client import AcsClient
from aliyunsdkcore.request import CommonRequest


logger = logging.getLogger()
# 資源的合規類型。
COMPLIANCE_TYPE_COMPLIANT = 'COMPLIANT'
COMPLIANCE_TYPE_NON_COMPLIANT = 'NON_COMPLIANT'
COMPLIANCE_TYPE_NOT_APPLICABLE = 'NOT_APPLICABLE'
# 資源配置的推送類型。
CONFIGURATION_TYPE_COMMON = 'COMMON'
CONFIGURATION_TYPE_OVERSIZE = 'OVERSIZE'
CONFIGURATION_TYPE_NONE = 'NONE'


# 入口函數，完成商務邏輯編排和處理。
def handler(event, context):
    """
    處理函數
    :param event：事件
    :param context：上下文
    :return：評估結果
    """
    # 校正Event，代碼可直接複製。
    evt = validate_event(event)
    if not evt:
        return None
    creds = context.credentials
    rule_parameters = evt.get('ruleParameters')
    result_token = evt.get('resultToken')
    invoking_event = evt.get('invokingEvent')
    ordering_timestamp = evt.get('orderingTimestamp')

    # 資源的配置資訊。規則引發機制需要設定為配置變更。當您建立規則或手動執行規則時，配置審計會逐個調用函數觸發對所有資源的評估。如果資源配置發生變更，配置審計根據變更的資源資訊自動調用函數觸發一次資源評估。
    configuration_item = invoking_event.get('configurationItem')
    account_id = configuration_item.get('accountId')
    resource_id = configuration_item.get('resourceId')
    resource_type = configuration_item.get('resourceType')
    region_id = configuration_item.get('regionId')

    # 判斷當前推送的資源配置資訊是否大於等於配置（100 KB），如果是，則需要調用GetDiscoveredResource查詢資源詳情。
    configuration_type = invoking_event.get('configurationType')
    if configuration_type and configuration_type == CONFIGURATION_TYPE_OVERSIZE:
        resource_result = get_discovered_resource(creds, resource_id, resource_type, region_id)
        resource_json = json.loads(resource_result)
        configuration_item["configuration"] = resource_json["DiscoveredResourceDetail"]["Configuration"]

    # 對資源進行評估，需要根據實際業務自行實現評估邏輯，以下代碼僅供參考。
    compliance_type, annotation = evaluate_configuration_item(
        rule_parameters, configuration_item)

    # 設定評估結果，格式需符合以下樣本要求。
    evaluations = [
        {
            'accountId': account_id,
            'complianceResourceId': resource_id,
            'complianceResourceType': resource_type,
            'complianceRegionId': region_id,
            'orderingTimestamp': ordering_timestamp,
            'complianceType': compliance_type,
            'annotation': annotation
        }
    ]

    # 返回評估結果並寫入配置審計，代碼可直接複製。
    put_evaluations(creds, result_token, evaluations)
    return evaluations


# 根據規則資訊和資源配置進行評估。需要根據實際業務自行實現評估邏輯，以下代碼僅供參考。
def evaluate_configuration_item(rule_parameters, configuration_item):
    """
    評估邏輯
    :param rule_parameters：規則資訊
    :param configuration_item：資源配置
    :return：評估類型
    """
    # 初始化傳回值
    compliance_type = COMPLIANCE_TYPE_NON_COMPLIANT
    annotation = None

    # 擷取資源配置完整資訊
    full_configuration = configuration_item['configuration']
    if not full_configuration:
        annotation = 'Configuration is empty.'
        return compliance_type, annotation

    # 轉換為JSON
    configuration = parse_json(full_configuration)
    if not configuration:
        annotation = 'Configuration:{} is invalid.'.format(full_configuration)
        return compliance_type, annotation
    return compliance_type, annotation


def validate_event(event):
    """
    校正Event
    :param event：Event
    :return：JSON對象
    """
    if not event:
        logger.error('Event is empty.')
    evt = parse_json(event)
    logger.info('Loading event: %s .' % evt)

    if 'resultToken' not in evt:
        logger.error('ResultToken is empty.')
        return None
    if 'ruleParameters' not in evt:
        logger.error('RuleParameters is empty.')
        return None
    if 'invokingEvent' not in evt:
        logger.error('InvokingEvent is empty.')
        return None
    return evt


def parse_json(content):
    """
    JSON類型轉換
    :param content：JSON字串
    :return：JSON對象
    """
    try:
        return json.loads(content)
    except Exception as e:
        logger.error('Parse content:{} to json error:{}.'.format(content, e))
        return None


# 返回評估結果，並寫入配置審計，代碼可直接複製。
def put_evaluations(creds, result_token, evaluations):
    """
    調用API返回並寫入評估結果。
    :param context：Function Compute上下文
    :param result_token：回調令牌
    :param evaluations：評估結果
    :return: None
    """
    # 需具備許可權AliyunConfigFullAccess的Function ComputeFC的服務角色。
    client = AcsClient(creds.access_key_id, creds.access_key_secret, region_id='ap-southeast-1')

    # 建立Request，並設定參數，Domain為config.ap-southeast-1.aliyuncs.com。
    request = CommonRequest()
    request.set_domain('config.ap-southeast-1.aliyuncs.com')
    request.set_version('2019-01-08')
    request.set_action_name('PutEvaluations')
    request.add_body_params('ResultToken', result_token)
    request.add_body_params('Evaluations', evaluations)
    request.add_body_params('SecurityToken', creds.security_token)
    request.set_method('POST')

    try:
        response = client.do_action_with_exception(request)
        logger.info('PutEvaluations with request: {}, response: {}.'.format(request, response))
    except Exception as e:
        logger.error('PutEvaluations error: %s' % e)


# 擷取資源詳情，代碼可直接複製。
def get_discovered_resource(creds, resource_id, resource_type, region_id):
    """
    調用API擷取資源配置詳情
    :param context：Function Compute上下文
    :param resource_id：資源ID
    :param resource_type：資源類型
    :param region_id：資源所屬地區ID
    :return: 資源詳情
    """
    # 需具備許可權AliyunConfigFullAccess的Function ComputeFC的服務角色。
    client = AcsClient(creds.access_key_id, creds.access_key_secret, region_id='ap-southeast-1')

    request = CommonRequest()
    request.set_domain('config.ap-southeast-1.aliyuncs.com')
    request.set_version('2020-09-07')
    request.set_action_name('GetDiscoveredResource')
    request.add_query_param('ResourceId', resource_id)
    request.add_query_param('ResourceType', resource_type)
    request.add_query_param('Region', region_id)
    request.add_query_param('SecurityToken', creds.security_token)
    request.set_method('GET')

    try:
        response = client.do_action_with_exception(request)
        resource_result = str(response, encoding='utf-8')
        return resource_result
    except Exception as e:
        logger.error('GetDiscoveredResource error: %s' % e)

重要

推薦您通過配置審計控制台查看代碼中資源配置（configuration）的核心參數，擷取待設定規則的參數名稱。具體操作，請參見查看資源資訊中的步驟 6。

函數入參

Function Compute的函數入參包括資源配置和規則資訊兩部分。資源配置資訊儲存在configurationItem中，規則的入參資訊儲存在ruleParameters中。配置審計向Function Compute推送的內容因規則的觸發機制而不同，具體如下：

說明

關於如何從Function Compute中擷取函數入參，請參見查看調用日誌。

當規則的觸發機制僅設定為周期執行時，配置審計不會推送資源配置資訊至Function Compute。

當新建立規則初次執行、規則周期自動執行和規則手動觸發執行時，配置審計只會推送一條不包含資源配置資訊的記錄，JSON樣本如下：

{
    "orderingTimestamp": 1716365226714,
    "invokingEvent": {
        "accountId": 120886317861****,
        "messageType": "ScheduledNotification",
        "notificationCreationTimestamp": 1716365226714,
        "configurationType": "NONE"
    },
    "ruleParameters": {
        "CpuCount": "2"
    },
    "resultToken": "HLQr3BZx/C+DLjwudFcYdXxZFPF2HnGqlg1uHceZ5kDEFeQF2K5LZGofyhn+GE4NP5VgkwANUH3qcdeSjWwODk1ymtmLWLzFV4JForVWYIKdbwwhbDBOgVwF7Ov9c3uVCNz/KpxNElwhTzMkZB95U1vmLs4vUYXuB/Txw4jiCYBYZZnVumhwXWswTLvAhIe5Y451FckObyM3I47AaB+4KtDW3I5q8O+Kx7eSYkqqGTawmJEYjvWXz9CHHMLFtNYyJX54a35mpVdxFSvgeXYDJTStxqb+d9UH/162fZh7T78OHxpQZgl8bcXzZhml****"
}

當規則的觸發機制包括配置變更時，配置審計會推送資源配置資訊至Function Compute。

當新建立規則初次執行、規則周期自動執行和規則手動觸發執行時，配置審計會將資源配置資訊逐條推送至Function Compute。當新增資源或已有資源發生變化時，配置審計僅將變更的單個資源配置資訊推送至Function Compute，JSON樣本如下：

{
    "orderingTimestamp":1695786337959,
    "invokingEvent":{
        "accountId":120886317861****,
        "messageType":"Manual",
        "notificationCreationTimestamp":1695786337959,
        "configurationType":"COMMON",
        "configurationItem":{
            "accountId":120886317861****,
            "arn":"acs:ecs:ap-southeast-1:120886317861****:instance/i-t4n0vr6x7v54jdbu****",
            "availabilityZone":"ap-southeast-1a",
            "regionId":"ap-southeast-1",
            "configuration":"{\\"ResourceGroupId\\":\\"\\",\\"Memory\\":4096,\\"InstanceChargeType\\":\\"PostPaid\\",\\"Cpu\\":2,\\"OSName\\":\\"Alibaba Cloud Linux  3.2104 LTS 64\xe4\xbd\x8d\\",\\"InstanceNetworkType\\":\\"vpc\\",\\"InnerIpAddress\\":{\\"IpAddress\\":[]},\\"ExpiredTime\\":\\"2099-12-31T15:59Z\\",\\"ImageId\\":\\"aliyun_3_x64_20G_alibase_20230727.vhd\\",\\"EipAddress\\":{\\"AllocationId\\":\\"\\",\\"IpAddress\\":\\"\\",\\"InternetChargeType\\":\\"\\"},\\"ImageOptions\\":{},\\"VlanId\\":\\"\\",\\"HostName\\":\\"iZt4n0vr6x7v54jdbuk****\\",\\"Status\\":\\"Running\\",\\"HibernationOptions\\":{\\"Configured\\":false},\\"MetadataOptions\\":{\\"HttpTokens\\":\\"\\",\\"HttpEndpoint\\":\\"\\"},\\"InstanceId\\":\\"i-t4n0vr6x7v54jdbu****\\",\\"StoppedMode\\":\\"Not-applicable\\",\\"CpuOptions\\":{\\"ThreadsPerCore\\":2,\\"Numa\\":\\"ON\\",\\"CoreCount\\":1},\\"StartTime\\":\\"2023-08-18T09:02Z\\",\\"DeletionProtection\\":false,\\"VpcAttributes\\":{\\"PrivateIpAddress\\":{\\"IpAddress\\":[\\"192.168.XX.XX\\"]},\\"VpcId\\":\\"vpc-t4nmwd0l9a7aj09yr****\\",\\"VSwitchId\\":\\"vsw-t4njclm0dlz2szayi****\\",\\"NatIpAddress\\":\\"\\"},\\"SecurityGroupIds\\":{\\"SecurityGroupId\\":[\\"sg-t4n5pulxj2lvechw****\\"]},\\"InternetChargeType\\":\\"PayByTraffic\\",\\"InstanceName\\":\\"zs-test-peer****\\",\\"DeploymentSetId\\":\\"\\",\\"InternetMaxBandwidthOut\\":0,\\"SerialNumber\\":\\"8c3fadf7-2ea1-4486-84ce-7784aeb7****\\",\\"OSType\\":\\"linux\\",\\"CreationTime\\":\\"2023-08-18T09:02Z\\",\\"AutoReleaseTime\\":\\"\\",\\"Description\\":\\"\\",\\"InstanceTypeFamily\\":\\"ecs.c7\\",\\"DedicatedInstanceAttribute\\":{\\"Tenancy\\":\\"\\",\\"Affinity\\":\\"\\"},\\"PublicIpAddress\\":{\\"IpAddress\\":[]},\\"GPUSpec\\":\\"\\",\\"NetworkInterfaces\\":{\\"NetworkInterface\\":[{\\"Type\\":\\"Primary\\",\\"PrimaryIpAddress\\":\\"192.168.XX.XX\\",\\"MacAddress\\":\\"00:16:3e:04:XX:XX\\",\\"NetworkInterfaceId\\":\\"eni-t4n16tmnpp794y1o****\\",\\"PrivateIpSets\\":{\\"PrivateIpSet\\":[{\\"PrivateIpAddress\\":\\"192.168.XX.XX\\",\\"Primary\\":true}]}}]},\\"SpotPriceLimit\\":0.0,\\"SaleCycle\\":\\"\\",\\"DeviceAvailable\\":true,\\"InstanceType\\":\\"ecs.c7.large\\",\\"OSNameEn\\":\\"Alibaba Cloud Linux  3.2104 LTS 64 bit\\",\\"SpotStrategy\\":\\"NoSpot\\",\\"IoOptimized\\":true,\\"ZoneId\\":\\"ap-southeast-1a\\",\\"ClusterId\\":\\"\\",\\"EcsCapacityReservationAttr\\":{\\"CapacityReservationPreference\\":\\"\\",\\"CapacityReservationId\\":\\"\\"},\\"DedicatedHostAttribute\\":{\\"DedicatedHostId\\":\\"\\",\\"DedicatedHostName\\":\\"\\",\\"DedicatedHostClusterId\\":\\"\\"},\\"GPUAmount\\":0,\\"OperationLocks\\":{\\"LockReason\\":[]},\\"InternetMaxBandwidthIn\\":-1,\\"Recyclable\\":false,\\"RegionId\\":\\"ap-southeast-1\\",\\"CreditSpecification\\":\\"\\"}",
            "captureTime":1695786337959,
            "resourceCreateTime":1692349320000,
            "resourceId":"i-t4n0vr6x7v54jdbu****",
            "resourceName":"zs-test-peer****",
            "resourceGroupId":"rg-acfmw3ty5y7****",
            "resourceType":"ACS::ECS::Instance",
            "tags":"{}"
        }
    },
    "ruleParameters":{
        "CpuCount":"2"
    },
    "resultToken":"HLQr3BZx/C+DLjwudFcYdXxZFPF2HnGqlg1uHceZ5kDEFeQF2K5LZGofyhn+GE4NP5VgkwANUH3qcdeSjWwODk1ymtmLWLzFV4JForVWYIKdbwwhbDBOgVwF7Ov9c3uVCNz/KpxNElwhTzMkZB95U1vmLs4vUYXuB/Txw4jiCYBYZZnVumhwXWswTLvAhIe5Y451FckObyM3I47AaB+4KtDW3I5q8O+Kx7eSYkqqGTawmJEYjvWXz9CHHMLFtNYyJX54a35mpVdxFSvgeXYDJTStxqb+d9UH/162fZh7T78OHxpQZgl8bcXzZhml****"
}

當推送的資源配置資訊大於等於100 KB時，配置審計只推送資源的摘要資訊，不包含資源配置的configuration欄位，JSON樣本如下：

說明

當您需要擷取完整的資源配置資訊時，可調用介面GetDiscoveredResource。

{
    "orderingTimestamp":1695786337959,
    "invokingEvent":{
        "accountId":120886317861****,
        "messageType":"Manual",
        "notificationCreationTimestamp":1695786337959,
        "configurationType":"OVERSIZE",
        "configurationItem":{
            "accountId":120886317861****,
            "arn":"acs:ecs:ap-southeast-1:120886317861****:instance/i-t4n0vr6x7v54jdbu****",
            "availabilityZone":"ap-southeast-1a",
            "regionId":"ap-southeast-1",
            "captureTime":1695786337959,
            "resourceCreateTime":1692349320000,
            "resourceId":"i-t4n0vr6x7v54jdbu****",
            "resourceName":"zs-test-peer****",
            "resourceGroupId":"rg-acfmw3ty5y7****",
            "resourceType":"ACS::ECS::Instance",
            "tags":"{}"
        }
    },
    "ruleParameters":{
        "CpuCount":"2"
    },
    "resultToken":"HLQr3BZx/C+DLjwudFcYdXxZFPF2HnGqlg1uHceZ5kDEFeQF2K5LZGofyhn+GE4NP5VgkwANUH3qcdeSjWwODk1ymtmLWLzFV4JForVWYIKdbwwhbDBOgVwF7Ov9c3uVCNz/KpxNElwhTzMkZB95U1vmLs4vUYXuB/Txw4jiCYBYZZnVumhwXWswTLvAhIe5Y451FckObyM3I47AaB+4KtDW3I5q8O+Kx7eSYkqqGTawmJEYjvWXz9CHHMLFtNYyJX54a35mpVdxFSvgeXYDJTStxqb+d9UH/162fZh7T78OHxpQZgl8bcXzZhml****"
}

函數入參的分類及其主要參數說明如下表所示。

分類	參數	描述
資源配置	configurationItem	資源的配置資訊。包括：資源所屬的阿里雲帳號ID、資源的ARN、資源所屬的可用性區域、資源所屬的地區、資源的詳細配置、配置審計發現資源變更事件並組建記錄檔的時間戳記、建立資源的時間戳記、資源狀態、資源ID、資源名稱、資源類型和標籤。
資源配置	configurationType	資源配置的推送類型。取值： COMMON：當`configurationItem`小於100 KB時，資源的配置資訊正常推送。 OVERSIZE：當`configurationItem`大於等於100 KB時，調用GetDiscoveredResource介面查詢資源詳情。
規則資訊	orderingTimestamp	評估執行的開始時間戳。
	invokingEvent	呼叫事件。
	accountId	呼叫事件的帳號ID。
	messageType	訊息類型。取值： Manual：手動執行。 ConfigurationItemChangeNotification：配置變更。 ScheduledNotification：周期執行。
	notificationCreationTimestamp	規則引發時的時間戳記。
	ruleParameters	自訂規則的入參。包括：規則入參名稱和期望值。
	resultToken	Function Compute中的回調令牌。