Custom fields for cloud resources

This page explains how to extend the default audit data collected from cloud resources by creating custom audit fields. These fields allow you to collect additional, resource-specific information during audits in AWS and Azure cloud resources using PowerShell scripts.

To add a new custom field for cloud resources:

1. On the Custom audit fields page, click to start the process of creating a new custom field. The Add new field dialog is displayed.

2. Provide the following parameters:

   • Label: The label for the field, which will be displayed in audit results.

   • Name: A descriptive name for the field.

   • Resource type: Select a cloud resource type (for example, AWS EC2 instance, AWS DB instance, or Azure instance).

   • Field type: Select a data type that matches the value returned by the script, such as String, DateTime, Logical, etc.

   • Script: Provide a PowerShell script that retrieves the required data for each resource. You can enter the script manually or load it from a file.

   • Description: A brief explanation of the field's purpose.

Once the custom field is created, the PowerShell script runs during the audit for each resource of the selected type, and the returned value is stored in the field.

PowerShell script guidelines

For cloud resources, scripts query AWS or Azure using PowerShell cmdlets and return data for a specific resource.

Cloud scripts often require additional PowerShell modules that are not installed by default.

For example:

• AWS: AWSPowerShell, AWS.Tools.*

• Azure: Az module

These modules must be available on the audit service machine before the script runs. You can either enable Allow module installation on audit service host in the audit service settings so missing modules can be installed automatically, or install the required modules manually. See Audit service settings for details.

If a required module is missing, the script will fail during execution. Error messages will indicate which cmdlets or modules are not available.

Using the $id variable

Each script can use the predefined $id variable, which contains the unique identifier of the audited resource:

• For AWS: resource ID (for example, EC2 instance ID or AMI ID)

• For Azure: resource identifier

In most cases, the script uses $id to retrieve data for the specific resource being audited.

The connection to the cloud provider is already initialized by the audit service using the configured credentials. This means the script can directly use AWS or Azure cmdlets without additional authentication setup.

Typical script flow:

1. Use $id to identify the resource

2. Call an AWS or Azure cmdlet to retrieve the resource

3. Extract the required property

4. Convert the value if needed

5. Return the result

Example

The following example retrieves the list of security groups assigned to an EC2 instance and returns them as a comma-separated string.

		# Fetch instance details using the resource ID
		$instance = Get-EC2Instance -InstanceId $id

		# Extract group names and join them into a single string
		$result = ($instance.Instances.SecurityGroups.GroupName) -join ','

		return $result

How this script works:

• The script uses $id to identify the EC2 instance being audited.

• The Get-EC2Instance cmdlet retrieves instance details from AWS.

• The script accesses the SecurityGroups.GroupName property, which may contain multiple values.

• These values are combined into a single comma-separated string using -join ','.

• The result is assigned to $result and returned as a String value.