diff --git a/CHANGELOG.md b/CHANGELOG.md index baf41820..2f6cc35f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,8 @@ +## 6.5.1 +- Fix Find-VdcObject documentation page not building, [#302](https://github.com/Venafi/VenafiPS/issues/302) +- Rebranding post CyberArk acquisition +- Add specific exception types when working with invalid paths or access issues on VDC objects + ## 6.5.0 - Merge all functions into 1 psm1 module. This yields much better performance, especially when running multithreaded. - Add multithreading support on PS v5 with the Microsoft.PowerShell.ThreadJob module (installed separately). If the module isn't installed, multithreading will be disabled. Set `-ThrottleLimit` to 1 on the functions that support it to disable multithreading on PS v5 and v7. @@ -728,5 +733,6 @@ This is a major release. Although every attempt has been made to be backwards c + diff --git a/VenafiPS/VenafiPS.psd1 b/VenafiPS/VenafiPS.psd1 index 87e1a9ee..66a85dc4 100644 --- a/VenafiPS/VenafiPS.psd1 +++ b/VenafiPS/VenafiPS.psd1 @@ -3,7 +3,7 @@ # # Generated by: Greg Brownstein # -# Generated on: 10/01/2024 +# Generated on: 10/09/2024 # @{ @@ -12,7 +12,7 @@ RootModule = 'VenafiPS.psm1' # Version number of this module. -ModuleVersion = '6.5.0' +ModuleVersion = '6.5.1' # Supported PSEditions # CompatiblePSEditions = @() @@ -69,7 +69,46 @@ PowerShellVersion = '5.1' # NestedModules = @() # Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export. -FunctionsToExport = @('Add-VcCertificateAssociation','Add-VcTeamMember','Add-VcTeamOwner','Add-VdcAdaptableHash','Add-VdcCertificateAssociation','Add-VdcEngineFolder','Add-VdcTeamMember','Add-VdcTeamOwner','Convert-VdcObject','ConvertTo-VdcGuid','ConvertTo-VdcPath','Export-VcCertificate','Export-VdcCertificate','Export-VdcVaultObject','Find-VcCertificate','Find-VcCertificateInstance','Find-VcCertificateRequest','Find-VcLog','Find-VcMachine','Find-VcMachineIdentity','Find-VdcCertificate','Find-VdcClient','Find-VdcEngine','Find-VdcIdentity','Find-VdcObject','Find-VdcVaultId','Get-VcApplication','Get-VcCertificate','Get-VcConnector','Get-VcIssuingTemplate','Get-VcMachine','Get-VcMachineIdentity','Get-VcSatellite','Get-VcTag','Get-VcTeam','Get-VcUser','Get-VcWebhook','Get-VdcAttribute','Get-VdcCertificate','Get-VdcClassAttribute','Get-VdcCredential','Get-VdcCustomField','Get-VdcEngineFolder','Get-VdcIdentity','Get-VdcIdentityAttribute','Get-VdcObject','Get-VdcPermission','Get-VdcSystemStatus','Get-VdcTeam','Get-VdcVersion','Get-VdcWorkflowTicket','Import-VcCertificate','Import-VdcCertificate','Invoke-VcCertificateAction','Invoke-VcWorkflow','Invoke-VdcCertificateAction','Invoke-VenafiRestMethod','Move-VdcObject','New-VcApplication','New-VcCertificate','New-VcConnector','New-VcMachine','New-VcMachineCommonKeystore','New-VcMachineIis','New-VcTeam','New-VcWebhook','New-VdcCapiApplication','New-VdcCertificate','New-VdcCustomField','New-VdcDevice','New-VdcObject','New-VdcPolicy','New-VdcTeam','New-VdcToken','New-VenafiSession','Read-VdcLog','Remove-VcApplication','Remove-VcCertificate','Remove-VcConnector','Remove-VcIssuingTemplate','Remove-VcMachine','Remove-VcMachineIdentity','Remove-VcTag','Remove-VcTeam','Remove-VcTeamMember','Remove-VcTeamOwner','Remove-VcWebhook','Remove-VdcCertificate','Remove-VdcCertificateAssociation','Remove-VdcClient','Remove-VdcEngineFolder','Remove-VdcObject','Remove-VdcPermission','Remove-VdcTeam','Remove-VdcTeamMember','Remove-VdcTeamOwner','Rename-VdcObject','Revoke-VdcGrant','Revoke-VdcToken','Search-VdcHistory','Set-VcApplication','Set-VcConnector','Set-VcTeam','Set-VdcAttribute','Set-VdcCredential','Set-VdcPermission','Set-VdcWorkflowTicketStatus','Test-VdcIdentity','Test-VdcObject','Test-VdcToken','Write-VdcLog') +FunctionsToExport = 'Add-VcCertificateAssociation', 'Add-VcTeamMember', 'Add-VcTeamOwner', + 'Add-VdcAdaptableHash', 'Add-VdcCertificateAssociation', + 'Add-VdcEngineFolder', 'Add-VdcTeamMember', 'Add-VdcTeamOwner', + 'Convert-VdcObject', 'ConvertTo-VdcGuid', 'ConvertTo-VdcPath', + 'Export-VcCertificate', 'Export-VdcCertificate', + 'Export-VdcVaultObject', 'Find-VcCertificate', + 'Find-VcCertificateInstance', 'Find-VcCertificateRequest', + 'Find-VcLog', 'Find-VcMachine', 'Find-VcMachineIdentity', + 'Find-VdcCertificate', 'Find-VdcClient', 'Find-VdcEngine', + 'Find-VdcIdentity', 'Find-VdcObject', 'Find-VdcVaultId', + 'Get-VcApplication', 'Get-VcCertificate', 'Get-VcConnector', + 'Get-VcIssuingTemplate', 'Get-VcMachine', 'Get-VcMachineIdentity', + 'Get-VcSatellite', 'Get-VcTag', 'Get-VcTeam', 'Get-VcUser', + 'Get-VcWebhook', 'Get-VdcAttribute', 'Get-VdcCertificate', + 'Get-VdcClassAttribute', 'Get-VdcCredential', 'Get-VdcCustomField', + 'Get-VdcEngineFolder', 'Get-VdcIdentity', 'Get-VdcIdentityAttribute', + 'Get-VdcObject', 'Get-VdcPermission', 'Get-VdcSystemStatus', + 'Get-VdcTeam', 'Get-VdcVersion', 'Get-VdcWorkflowTicket', + 'Import-VcCertificate', 'Import-VdcCertificate', + 'Invoke-VcCertificateAction', 'Invoke-VcWorkflow', + 'Invoke-VdcCertificateAction', 'Invoke-VenafiRestMethod', + 'Move-VdcObject', 'New-VcApplication', 'New-VcCertificate', + 'New-VcConnector', 'New-VcMachine', 'New-VcMachineCommonKeystore', + 'New-VcMachineIis', 'New-VcTeam', 'New-VcWebhook', + 'New-VdcCapiApplication', 'New-VdcCertificate', 'New-VdcCustomField', + 'New-VdcDevice', 'New-VdcObject', 'New-VdcPolicy', 'New-VdcTeam', + 'New-VdcToken', 'New-VenafiSession', 'Read-VdcLog', + 'Remove-VcApplication', 'Remove-VcCertificate', 'Remove-VcConnector', + 'Remove-VcIssuingTemplate', 'Remove-VcMachine', + 'Remove-VcMachineIdentity', 'Remove-VcTag', 'Remove-VcTeam', + 'Remove-VcTeamMember', 'Remove-VcTeamOwner', 'Remove-VcWebhook', + 'Remove-VdcCertificate', 'Remove-VdcCertificateAssociation', + 'Remove-VdcClient', 'Remove-VdcEngineFolder', 'Remove-VdcObject', + 'Remove-VdcPermission', 'Remove-VdcTeam', 'Remove-VdcTeamMember', + 'Remove-VdcTeamOwner', 'Rename-VdcObject', 'Revoke-VdcGrant', + 'Revoke-VdcToken', 'Search-VdcHistory', 'Set-VcApplication', + 'Set-VcConnector', 'Set-VcTeam', 'Set-VdcAttribute', + 'Set-VdcCredential', 'Set-VdcPermission', + 'Set-VdcWorkflowTicketStatus', 'Test-VdcIdentity', 'Test-VdcObject', + 'Test-VdcToken', 'Write-VdcLog' # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export. CmdletsToExport = @() diff --git a/docs/changelog.md b/docs/changelog.md index 83063e5c..19348deb 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,3 +1,8 @@ +## 6.5.1 +- Fix Find-VdcObject documentation page not building, [#302](https://github.com/Venafi/VenafiPS/issues/302) +- Rebranding post CyberArk acquisition +- Add specific exception types when working with invalid paths or access issues on VDC objects + ## 6.5.0 - Merge all functions into 1 psm1 module. This yields much better performance, especially when running multithreaded. - Add multithreading support on PS v5 with the Microsoft.PowerShell.ThreadJob module (installed separately). If the module isn't installed, multithreading will be disabled. Set `-ThrottleLimit` to 1 on the functions that support it to disable multithreading on PS v5 and v7. @@ -728,5 +733,6 @@ This is a major release. Although every attempt has been made to be backwards c + diff --git a/docs/functions/Find-VcObject.md b/docs/functions/Find-VcObject.md deleted file mode 100644 index 9bdfbf46..00000000 --- a/docs/functions/Find-VcObject.md +++ /dev/null @@ -1,228 +0,0 @@ -# Find-VcObject - -## SYNOPSIS -Find different objects on TLSPC - -## SYNTAX - -### All (Default) -``` -Find-VcObject -Type [-Name ] [-Order ] [-First ] - [-VenafiSession ] [-ProgressAction ] [] -``` - -### Filter -``` -Find-VcObject -Type -Filter [-Order ] - [-First ] [-VenafiSession ] [-ProgressAction ] [] -``` - -### SavedSearch -``` -Find-VcObject -Type -SavedSearchName [-First ] [-VenafiSession ] - [-ProgressAction ] [] -``` - -## DESCRIPTION -Find objects of type ActivityLog, Machine, MachineIdentity, CertificateRequest, CertificateInstance on TLSPC. -Supports -First for page size; the max page size is 1000. -To find certificate objects, use Find-VcCertificate. - -## EXAMPLES - -### EXAMPLE 1 -``` -Find-VcObject -Type CertificateInstance -``` - -Get all records - -### EXAMPLE 2 -``` -Find-VcObject -Type CertificateInstance -First 50 -``` - -Get first 50 records - -### EXAMPLE 3 -``` -Find-VcObject -Type ActivityLog -Filter @('activityType', 'eq', 'Notifications') -First 10 -``` - -Retrieve 10 records matching the field name - -### EXAMPLE 4 -``` -Find-VcObject -Type Certificate -Name searchme -``` - -Get all certificates where the name has 'searchme' in it - -### EXAMPLE 5 -``` -Find-VcObject -type Certificate -filter @('selfSigned','eq','True') -``` - -Get all self signed certificates - -### EXAMPLE 6 -``` -Find-VcObject -Type ActivityLog -Filter @('activityType', 'eq', 'Notifications') -First 10 -Order @{'activityDate'='desc'} -``` - -Retrieve the most recent 10 records matching the field name - -### EXAMPLE 7 -``` -Find-VcObject -Filter @('and', @('activityDate', 'gt', (get-date).AddMonths(-1)), @('or', @('userId', 'eq', 'ab0feb46-8df7-47e7-8da9-f47ab314f26a'), @('userId', 'eq', '933c28de-6352-46f3-bc12-bd96077e8eae'))) -``` - -Advanced filtering of results. -This filter will find log entries by 1 of 2 people within the last month. - -## PARAMETERS - -### -Type -Type of object to retrieve, either Certificate, ActivityLog, Machine, MachineIdentity, CertificateRequest, or CertificateInstance. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Name -Case sensitive name to search for. -The field to be searched is different for each object type. - -```yaml -Type: String -Parameter Sets: All -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Filter -Array or multidimensional array of fields and values to filter on. -Each array should be of the format @('operator', @(field, comparison operator, value), @(field2, comparison operator2, value2)). -Nested filters are supported. -For a complete list of comparison operators, see https://docs.venafi.cloud/api/about-api-search-operators/. - -```yaml -Type: System.Collections.Generic.List`1[System.Object] -Parameter Sets: Filter -Aliases: - -Required: True -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Order -Array of fields to order on. -For each item in the array, you can provide a field name by itself; this will default to ascending. -You can also provide a hashtable with the field name as the key and either asc or desc as the value. - -```yaml -Type: PSObject[] -Parameter Sets: All, Filter -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -SavedSearchName -{{ Fill SavedSearchName Description }} - -```yaml -Type: String -Parameter Sets: SavedSearch -Aliases: - -Required: True -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -First -Only retrieve this many records - -```yaml -Type: Int32 -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: 0 -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -VenafiSession -Authentication for the function. -The value defaults to the script session object $VenafiSession created by New-VenafiSession. -A TLSPC key can also provided. - -```yaml -Type: PSObject -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ProgressAction -{{ Fill ProgressAction Description }} - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -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). - -## INPUTS - -## OUTPUTS - -### PSCustomObject -## NOTES - -## RELATED LINKS - -[http://VenafiPS.readthedocs.io/en/latest/functions/Find-VcObject/](http://VenafiPS.readthedocs.io/en/latest/functions/Find-VcObject/) - -[https://github.com/Venafi/VenafiPS/blob/main/VenafiPS/Public/Find-VcObject.ps1](https://github.com/Venafi/VenafiPS/blob/main/VenafiPS/Public/Find-VcObject.ps1) - diff --git a/docs/functions/Find-VdcObject.md b/docs/functions/Find-VdcObject.md new file mode 100644 index 00000000..90a58951 --- /dev/null +++ b/docs/functions/Find-VdcObject.md @@ -0,0 +1,281 @@ +# Find-VdcObject + +## SYNOPSIS +Find objects by path, class, or pattern + +## SYNTAX + +### FindByPath (Default) +``` +Find-VdcObject [-Path ] [-Recursive] [-VenafiSession ] [-ProgressAction ] + [] +``` + +### FindByPattern +``` +Find-VdcObject [-Path ] -Pattern [-Recursive] [-VenafiSession ] + [-ProgressAction ] [] +``` + +### FindByClass +``` +Find-VdcObject [-Path ] [-Pattern ] -Class [-Recursive] [-VenafiSession ] + [-ProgressAction ] [] +``` + +### FindByAttribute +``` +Find-VdcObject -Pattern -Attribute [-NoLookup] [-VenafiSession ] + [-ProgressAction ] [] +``` + +## DESCRIPTION +Find objects by path, class, or pattern. + +## EXAMPLES + +### EXAMPLE 1 +``` +Find-VdcObject +Get all objects recursively starting from \ved\policy +``` + +### EXAMPLE 2 +``` +Find-VdcObject -Path '\VED\Policy\certificates' +Get all objects in the root of a specific folder +``` + +### EXAMPLE 3 +``` +Find-VdcObject -Path '\VED\Policy\My Folder' -Recursive +Get all objects in a folder and subfolders +``` + +### EXAMPLE 4 +``` +Find-VdcObject -Path '\VED\Policy' -Pattern '*test*' +Get items in a specific folder filtering the path +``` + +### EXAMPLE 5 +``` +Find-VdcObject -Class 'capi' -Path '\ved\policy\installations' -Recursive +Get objects of a specific type +``` + +### EXAMPLE 6 +``` +Find-VdcObject -Class 'capi' -Pattern '*test*' -Path '\ved\policy\installations' -Recursive +Get all objects of a specific type where the path is of a specific pattern +``` + +### EXAMPLE 7 +``` +Find-VdcObject -Class 'capi', 'iis6' -Pattern '*test*' -Path '\ved\policy\installations' -Recursive +Get objects for multiple types +``` + +### EXAMPLE 8 +``` +Find-VdcObject -Pattern '*f5*' +Find objects with the specific name. All objects under \ved\policy (the default) will be searched. +``` + +### EXAMPLE 9 +``` +Find-VdcObject -Attribute 'Description' -Pattern 'awesome' +Find objects where the specific attribute matches the pattern +``` + +### EXAMPLE 10 +``` +Find-VdcObject -Attribute 'Environment' -Pattern 'Development' +``` + +Find objects where a custom field value matches the pattern. +By default, the attribute will be checked against the current list of custom fields. + +### EXAMPLE 11 +``` +Find-VdcObject -Attribute 'Description' -Pattern 'duplicate' -NoLookup +``` + +Bypass custom field lookup and force Attribute to be treated as a built-in attribute. +Useful if there are conflicting custom field and built-in attribute names and you want to force the lookup against built-in. + +## PARAMETERS + +### -Path +The path to start our search. +The default is \ved\policy. + +```yaml +Type: String +Parameter Sets: FindByPath, FindByPattern, FindByClass +Aliases: DN + +Required: False +Position: Named +Default value: \ved\policy +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Pattern +Filter against object paths. +If the Attribute parameter is provided, this will filter against an object's attribute/custom field values instead of the path. + +Follow the below rules: +- To list DNs that include an asterisk or question mark, prepend the character with two backslashes. +- To list DNs with a wildcard character, append a question mark (?). +For example, "test_?.mycompany.net" counts test_1.MyCompany.net and test_2.MyCompany.net but not test12.MyCompany.net. +- To list DNs with similar names, prepend an asterisk. +For example, *est.MyCompany.net, counts Test.MyCompany.net and West.MyCompany.net. +You can also use both literals and wildcards in a pattern. + +```yaml +Type: String +Parameter Sets: FindByPattern, FindByAttribute +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +```yaml +Type: String +Parameter Sets: FindByClass +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Class +1 or more classes/types to search for + +```yaml +Type: String[] +Parameter Sets: FindByClass +Aliases: TypeName + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Attribute +A list of attribute names to limit the search against. +Only valid when searching by pattern. +A custom field name can also be provided. + +```yaml +Type: String[] +Parameter Sets: FindByAttribute +Aliases: AttributeName + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Recursive +Searches the subordinates of the object specified in Path. + +```yaml +Type: SwitchParameter +Parameter Sets: FindByPath, FindByPattern, FindByClass +Aliases: r + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoLookup +Default functionality when finding by Attribute is to perform a lookup to see if they are custom fields or not. +If they are, pass along the guid instead of name required by the api for custom fields. +To override this behavior and use the attribute name as is, add -NoLookup. +Useful if on the off chance you have a custom field with the same name as a built-in attribute. + +```yaml +Type: SwitchParameter +Parameter Sets: FindByAttribute +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -VenafiSession +Authentication for the function. +The value defaults to the script session object $VenafiSession created by New-VenafiSession. +A TLSPDC token can also be provided. +If providing a TLSPDC token, an environment variable named VDC_SERVER must also be set. + +```yaml +Type: PSObject +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction +{{ Fill ProgressAction Description }} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +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). + +## INPUTS + +### Path +## OUTPUTS + +### TppObject +## NOTES + +## RELATED LINKS + +[http://VenafiPS.readthedocs.io/en/latest/functions/Find-VdcObject/](http://VenafiPS.readthedocs.io/en/latest/functions/Find-VdcObject/) + +[https://github.com/Venafi/VenafiPS/blob/main/VenafiPS/Public/Find-VdcObject.ps1](https://github.com/Venafi/VenafiPS/blob/main/VenafiPS/Public/Find-VdcObject.ps1) + +[https://docs.venafi.com/Docs/current/TopNav/Content/SDK/WebSDK/r-SDK-POST-Config-find.php](https://docs.venafi.com/Docs/current/TopNav/Content/SDK/WebSDK/r-SDK-POST-Config-find.php) + +[https://docs.venafi.com/Docs/current/TopNav/Content/SDK/WebSDK/r-SDK-POST-Config-findobjectsofclass.php](https://docs.venafi.com/Docs/current/TopNav/Content/SDK/WebSDK/r-SDK-POST-Config-findobjectsofclass.php) + +[https://docs.venafi.com/Docs/current/TopNav/Content/SDK/WebSDK/r-SDK-POST-Config-enumerate.php](https://docs.venafi.com/Docs/current/TopNav/Content/SDK/WebSDK/r-SDK-POST-Config-enumerate.php) +