feat: add pci compliance audit functions (#291)

- Added cmdlets for auditing PCI Compliance in VMware Cloud Foundation 5.2 and later.
  - Added `Get-VCFCompliance` to retrieve a specific compliance audit result.
  - Added `Get-VCFComplianceConfiguration` to retrieve a list of all compliance configurations along with their applicable resource types and versions.
  - Added `Get-VCFComplianceHistory` to retrieve the history for all compliance audits that have been performed.
  - Added `Get-VCFComplianceStandard` to retrieve a list of all compliance audit standards and versions that are supported.
  - Added `Get-VCFCompliance` to retrieve a specific compliance audit result.
  - Added `New-VCFCompliance` to run a new compliance audit.

Signed-off-by: William Lam <wlam@vmware.com>
Co-authored-by: Ryan Johnson <ryan.johnson@broadcom.com>

CHANGELOG.md

@@ -4,22 +4,29 @@
 
 > Released: Unreleased
 
+- Added cmdlets for auditing PCI Compliance in VMware Cloud Foundation 5.2 and later.
+  - Added `Get-VCFCompliance` to retrieve a specific compliance audit result.
+  - Added `Get-VCFComplianceConfiguration` to retrieve a list of all compliance configurations along with their applicable resource types and versions.
+  - Added `Get-VCFComplianceHistory` to retrieve the history for all compliance audits that have been performed.
+  - Added `Get-VCFComplianceStandard` to retrieve a list of all compliance audit standards and versions that are supported.
+  - Added `Get-VCFCompliance` to retrieve a specific compliance audit result.
+  - Added `New-VCFCompliance` to run a new compliance audit.
+- Added `Export-VCFManagementDomainJsonSpec` to export the JSON specification required for bring-up from the Planning and Preparation workbook.
+- Enhanced the request headers to include `Content-Type` to ensure REST API calls do not error out.
+- Enhanced `ResponseException` function to accept optional `-Body` parameter to include the JSON payload for ease of debugging.
+- Enhanced `New-VCFWorkloadDomain` cmdlet to improve error handling.
+- Enhanced `New-VCFCommissionedHost` cmdlet to improve error handling.
+- Enhanced `New-VCFCommissionedHost` cmdlet with ability to use the host commission JSON specification provided by the SDDC Manager UI.
 - Updated `Get-VCFTask` cmdlet with additional exception message to catch.
 - Updated `Get-VCFSystemPrecheckTask` cmdlet with optional parameter `failureOnly`.
 - Updated `Get-VCFPersonality` cmdlet with optional parameter `name`.
 - Updated `New-VCFWorkloadDomain` cmdlet with optional parameter `validate` to validate the JSON specification.
-- Enhanced `New-VCFWorkloadDomain` cmdlet to improve error handling.
-- Enhanced `New-VCFCommissionedHost` cmdlet to improve error handling.
-- Enhanced `New-VCFCommissionedHost` cmdlet with ability to use the host commission JSON specification provided by the SDDC Manager UI.
-- Removed the deprecated `Commission-VCFHost` alias from `New-VCFCommissionedHost`.
-- Removed the deprecated `Decommission-VCFHost` alias from `Remove-VCFCommissionedHost`.
-- Removed the deprecated `Get-VCFNsxManagerCluster` alias from `Get-VCFNsxtCluster`.
-- Removed the deprecated `Get-VCFNsxEdgeCluster` alias from `Get-VCFEdgeCluster`.
-- Removed the deprecated `New-VCFNsxEdgeCluster` alias from `New-VCFEdgeCluster`.
-- Refactors `Invoke-VCFCommand` to run commands on SDDC Manager without the need for SSH across PowerShell editions and operating systems.
-- Added `Export-VCFManagementDomainJsonSpec` to export the JSON spec required for bringup from the Planning & Preparation Excel workbook.
-- Enhanced the VCF request headers to include `Content-Type` to ensure REST API calls do not error out
-- Enhanced `ResponseException` function to accept optional `-Body` parameter to include the JSON payload for ease of debugging
+- Refactored `Invoke-VCFCommand` to run commands on SDDC Manager without the need for SSH across PowerShell editions and operating systems.
+- Removed deprecated `Commission-VCFHost` alias from `New-VCFCommissionedHost`.
+- Removed deprecated `Decommission-VCFHost` alias from `Remove-VCFCommissionedHost`.
+- Removed deprecated `Get-VCFNsxManagerCluster` alias from `Get-VCFNsxtCluster`.
+- Removed deprecated `Get-VCFNsxEdgeCluster` alias from `Get-VCFEdgeCluster`.
+- Removed deprecated `New-VCFNsxEdgeCluster` alias from `New-VCFEdgeCluster`.
 
 ## v2.4.1
 

PowerVCF.psd1

@@ -11,7 +11,7 @@
     RootModule        = 'PowerVCF.psm1'
 
     # Version number of this module.
-    ModuleVersion     = '2.5.0.1014'
+    ModuleVersion     = '2.5.0.1015'
 
     # Supported PSEditions
     # CompatiblePSEditions = @()

PowerVCF.psm1

@@ -5950,6 +5950,243 @@ Export-ModuleMember -Function Update-VCFIdentityProvider
 
 #EndRegion APIs for managing Identity Providers
 
+#Region APIs for Compliance Service
+Function Get-VCFComplianceConfiguration {
+    <#
+        .SYNOPSIS
+        Retrieves the list of all compliance configurations along with their applicable resource types and versions.
+
+        .DESCRIPTION
+        The Get-VCFComplianceConfiguration cmdlet retrieves the list of all compliance configurations along with their applicable resource types and versions.
+
+        .EXAMPLE
+        Get-VCFComplianceConfiguration
+        This example shows how to retrieve a list of all compliance configurations.
+    #>
+
+    Try {
+        if ((Get-VCFManager -version) -ge '5.2.0') {
+            createHeader # Set the Accept and Authorization headers.
+            checkVCFToken # Validate the access token and refresh, if necessary.
+            $uri = "https://$sddcManager/v1/compliance-configurations"
+            $response = Invoke-RestMethod -Method GET -Uri $uri -Headers $headers
+            Return ($response).elements
+        } else {
+            Write-Warning "$msgVcfApiNotSupported $(Get-VCFManager -version)"
+        }
+    } Catch {
+        ResponseException -Object $_
+    }
+}
+Export-ModuleMember -Function Get-VCFComplianceConfiguration
+
+Function Get-VCFComplianceStandard {
+    <#
+        .SYNOPSIS
+        Retrieves the list of all compliance standards and versions that are supported.
+
+        .DESCRIPTION
+        The Get-VCFComplianceStandard cmdlet retrieves the the list of all compliance standards and versions that are supported.
+
+        .EXAMPLE
+        Get-VCFComplianceStandard
+        This example shows how to retrieve a list of all compliance standards and versions.
+    #>
+
+    Try {
+        if ((Get-VCFManager -version) -ge '5.2.0') {
+            createHeader # Set the Accept and Authorization headers.
+            checkVCFToken # Validate the access token and refresh, if necessary.
+            $uri = "https://$sddcManager/v1/compliance-standards"
+            $response = Invoke-RestMethod -Method GET -Uri $uri -Headers $headers
+            Return ($response).elements
+        } else {
+            Write-Warning "$msgVcfApiNotSupported $(Get-VCFManager -version)"
+        }
+    } Catch {
+        ResponseException -Object $_
+    }
+}
+Export-ModuleMember -Function Get-VCFComplianceStandard
+
+Function Get-VCFComplianceHistory {
+    <#
+        .SYNOPSIS
+        Retrieves the history for all compliance audits that have been performed.
+
+        .DESCRIPTION
+        The Get-VCFComplianceHistory cmdlet retrieves the history for all compliance audits that have been performed.
+
+        .EXAMPLE
+        Get-VCFIdentityProvider
+        This example shows how to retrieve the history for all compliance audits that have been performed.
+
+        .EXAMPLE
+        Get-VCFComplianceHistory
+    #>
+
+    Try {
+        if ((Get-VCFManager -version) -ge '5.2.0') {
+            createHeader # Set the Accept and Authorization headers.
+            checkVCFToken # Validate the access token and refresh, if necessary.
+            $uri = "https://$sddcManager/v1/compliance-audits"
+            $response = Invoke-RestMethod -Method GET -Uri $uri -Headers $headers
+            Return ($response).elements
+        } else {
+            Write-Warning "$msgVcfApiNotSupported $(Get-VCFManager -version)"
+        }
+    } Catch {
+        ResponseException -Object $_
+    }
+}
+Export-ModuleMember -Function Get-VCFComplianceHistory
+
+Function New-VCFCompliance {
+    <#
+        .SYNOPSIS
+        Performs a new compliance audit.
+
+        .DESCRIPTION
+        The Get-VCFIdentityProvider cmdlet retrieves the history for all compliance audits.
+
+        .EXAMPLE
+        New-VCFCompliance -resourceType "SDDC_MANAGER" -standardType "PCI" -standardVersion "4.0" -domainName "sfo-m01"
+        This example shows how to perform a new compliance audit.
+
+        .PARAMETER resourceType
+        Specifies the resource type for the compliance audit. Please use Get-VCFComplianceConfiguration to see available options.
+
+        .PARAMETER standardType
+        Specifies the compliance type for the compliance audit. Please use Get-VCFComplianceStandard to see available options.
+
+        .PARAMETER standardVersion
+        Specifies the compliance version for the compliance audit. Please use Get-VCFComplianceStandard to see available options.
+
+        .PARAMETER domainName
+        Specifies the name of the workload domain.
+    #>
+
+    Param (
+        [Parameter (Mandatory = $true)] [ValidateSet("SDDC_MANAGER")] [String]$resourceType = "SDDC_MANAGER",
+        [Parameter (Mandatory = $true)] [String]$standardType,
+        [Parameter (Mandatory = $true)] [String]$standardVersion,
+        [Parameter (Mandatory = $true)] [String]$domainName
+    )
+
+    $vcfWorkloadDomainDetails = Get-VCFWorkloadDomain -Name $domainName
+
+    Try {
+        if ((Get-VCFManager -version) -ge '5.2.0') {
+            createHeader # Set the Accept and Authorization headers.
+            checkVCFToken # Validate the access token and refresh, if necessary.
+            $uri = "https://$sddcManager/v1/domains/$($vcfWorkloadDomainDetails.id)/compliance-audits"
+
+            $spec = [Ordered]@{
+                "standardType"                         = $standardType
+                "standardVersion"                      = $standardVersion
+                "complianceResourcesConfigurationSpec" = @(
+                    @{
+                        "resources" = @(
+                            @{
+                                "resourceType" = $resourceType
+                            }
+                        )
+                    }
+                )
+            }
+
+            $body = $spec | ConvertTo-Json -Depth 4
+
+            $response = Invoke-RestMethod -Method POST -Uri $uri -Headers $headers -Body $body
+            Return $response
+        } else {
+            Write-Warning "$msgVcfApiNotSupported $(Get-VCFManager -version)"
+        }
+    } Catch {
+        ResponseException -Object $_ -body $body
+    }
+}
+Export-ModuleMember -Function New-VCFCompliance
+
+Function Get-VCFComplianceTask {
+    <#
+        .SYNOPSIS
+        Retrieves the compliance audit id and progress using the task id returned from the New-VCFCompliance operation.
+
+        .DESCRIPTION
+        The Get-VCFComplianceTask cmdlet retrieves the compliance audit id and progress using the task id returned from the New-VCFCompliance operation.
+
+        .EXAMPLE
+        Get-VCFComplianceTask -domainName "sfo-m01" -complianceTaskId "d22c47e0-8d38-43da-975b-938e7c59f4d6"
+        This example shows how to retrieve the compliance audit id and progress using the task id returned from the New-VCFCompliance operation.
+
+        .PARAMETER domainName
+        SSpecifies the name of the workload domain.
+
+        .PARAMETER complianceTaskId
+        Specifies the compliance task id returned from New-VCFCompliance.
+    #>
+
+    Param (
+        [Parameter (Mandatory = $true)] [String]$domainName,
+        [Parameter (Mandatory = $true)] [String]$complianceTaskId
+    )
+
+    $vcfWorkloadDomainDetails = Get-VCFWorkloadDomain -Name $domainName
+
+    Try {
+        if ((Get-VCFManager -version) -ge '5.2.0') {
+            createHeader # Set the Accept and Authorization headers.
+            checkVCFToken # Validate the access token and refresh, if necessary.
+            $uri = "https://$sddcManager/v1/domains/$($vcfWorkloadDomainDetails.id)/compliance-audits/tasks/${complianceTaskId}"
+            $response = Invoke-RestMethod -Method GET -Uri $uri -Headers $headers
+            Return $response
+        } else {
+            Write-Warning "$msgVcfApiNotSupported $(Get-VCFManager -version)"
+        }
+    } Catch {
+        ResponseException -Object $_
+    }
+}
+Export-ModuleMember -Function Get-VCFComplianceTask
+
+Function Get-VCFCompliance {
+    <#
+        .SYNOPSIS
+        Retrieves a specific compliance audit result.
+
+        .DESCRIPTION
+        The Get-VCFCompliance cmdlet retrieves a specific compliance audit result.
+
+        .EXAMPLE
+        Get-VCFCompliance -complianceAuditId "1758e972-8509-4dce-93d9-a303d7c35a41"
+        This example shows how to retrieve a specific compliance audit result.
+
+        .PARAMETER complianceAuditId
+        Specifies the compliance task id returned from Get-VCFComplianceTask or Get-VCFComplianceHistory.
+    #>
+
+    Param (
+        [Parameter (Mandatory = $true)] [String]$complianceAuditId
+    )
+
+    Try {
+        if ((Get-VCFManager -version) -ge '5.2.0') {
+            createHeader # Set the Accept and Authorization headers.
+            checkVCFToken # Validate the access token and refresh, if necessary.
+            $uri = "https://$sddcManager/v1/compliance-audits/${complianceAuditId}/compliance-audit-items"
+            $response = Invoke-RestMethod -Method GET -Uri $uri -Headers $headers
+            Return ($response).elements
+        } else {
+            Write-Warning "$msgVcfApiNotSupported $(Get-VCFManager -version)"
+        }
+    } Catch {
+        ResponseException -Object $_
+    }
+}
+Export-ModuleMember -Function Get-VCFCompliance
+#EndRegion APIs for Compliance Service
+
 #Region APIs for managing Validations (Not Exported)
 
 # The following functions are not exported since they are used internally by the cmdlets that manage the validations.

docs/documentation/functions/aria-suite/aria-operations-logs/Set-VCFVrliConnection.md

@@ -72,4 +72,4 @@ Accept wildcard characters: False
 
 ### Common Parameters
 
-This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

docs/documentation/functions/aria-suite/aria-operations/Get-VCFVrops.md

@@ -56,4 +56,4 @@ Accept wildcard characters: False
 
 ### Common Parameters
 
-This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

docs/documentation/functions/aria-suite/aria-operations/Set-VCFVropsConnection.md

@@ -72,4 +72,4 @@ Accept wildcard characters: False
 
 ### Common Parameters
 
-This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

docs/documentation/functions/aria-suite/aria-suite-lifecycle/New-VCFVrslcm.md

@@ -78,4 +78,4 @@ Accept wildcard characters: False
 
 ### Common Parameters
 
-This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

docs/documentation/functions/authentication/Connect-CloudBuilder.md

@@ -96,4 +96,4 @@ Accept wildcard characters: False
 
 ### Common Parameters
 
-This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

docs/documentation/functions/authentication/Request-VCFToken.md

@@ -100,4 +100,4 @@ Accept wildcard characters: False
 
 ### Common Parameters
 
-This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

docs/documentation/functions/avns/Add-VCFApplicationVirtualNetwork.md

@@ -80,4 +80,4 @@ Accept wildcard characters: False
 
 ### Common Parameters
 
-This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

docs/documentation/functions/avns/Get-VCFApplicationVirtualNetwork.md

@@ -76,4 +76,4 @@ Accept wildcard characters: False
 
 ### Common Parameters
 
-This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

docs/documentation/functions/backup-restore/Get-VCFRestoreTask.md

@@ -44,4 +44,4 @@ Accept wildcard characters: False
 
 ### Common Parameters
 
-This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).