AzureDevOpsDscNative.psd1
|
@{ RootModule = 'AzureDevOpsDscNative.psm1' # Version number of this module. # # This value is a fallback for local and CI builds only. Released versions are # driven by the git tag: the publish workflow sets $env:ModuleVersion from the # tag, and the build stamps that value into the packaged manifest instead of this # one. Do not hand-edit this to cut a release - push a vX.Y.Z tag. moduleVersion = '1.3.1' # ID used to uniquely identify this module GUID = 'e7eb078e-5e97-42be-ae8f-decb140fc38e' # Author of this module Author = 'ZanattaMichael' # Company or vendor of this module CompanyName = 'ZanattaMichael' # Copyright statement for this module Copyright = 'Copyright the DSC Community contributors and ZanattaMichael. All rights reserved.' # Description of the functionality provided by this module Description = 'A fork of the DSC Community AzureDevOpsDsc module with native DSC v3 support: every resource is discoverable and invokable by dsc.exe via the Microsoft.Adapter/PowerShell adapter, using generated adapted resource manifests, without requiring a wrapper resource.' # Minimum version of the Windows PowerShell engine required by this module PowerShellVersion = '7.0' # Minimum version of the common language runtime (CLR) required by this module CLRVersion = '4.0' # Functions to export from this module #FunctionsToExport = @() # Cmdlets to export from this module #CmdletsToExport = @() # Variables to export from this module VariablesToExport = @() # Aliases to export from this module AliasesToExport = @() # Import all the 'DSCClassResource', modules as part of this module NestedModules = @() DscResourcesToExport = @('AzDoGroupPermission','AzDoOrganizationGroup','AzDoProject','AzDoProjectServices','AzDoProjectGroup','AzDoGroupMember','AzDoGitRepository','AzDoGitPermission','AzDoAreaPermission','AzDoIterationPermission','AzDoWIPTags','AzDoAreaNodes','AzDoIterationNodes','AzDoBranchPolicy','AzDoVariableGroup','AzDoServiceConnection','AzDoPipelineEnvironment','AzDoAgentPool','AzDoAgentQueue','AzDoTeam','AzDoTeamMember','AzDoPipeline','AzDoPipelinePermission','AzDoEnvironmentApproval','AzDoVariableGroupPermission','AzDoServiceConnectionPermission','AzDoAgentPoolPermission','AzDoSecurityNamespacePermission','AzDoArtifactFeed','AzDoArtifactFeedPermission','AzDoDeploymentGroup','AzDoTaskGroup','AzDoOrganizationSettings','AzDoExtension','AzDoAuditStream','AzDoProjectPermission','AzDoEnvironmentPermission','AzDoWiki','AzDoNotificationSubscription','AzDoRepositorySettings','AzDoCheckConfiguration','AzDoTeamSettings','AzDoArtifactFeedSettings','AzDoArtifactFeedView','AzDoProcess','AzDoProcessPermission','AzDoUserEntitlement','AzDoServiceHook','AzDoPipelineSettings','AzDoQueryFolder','AzDoWorkItemQuery','AzDoQueryPermission','AzDoWIPTagHygiene','AzDoSecureFile','AzDoSecureFilePermission','AzDoPipelineFolder','AzDoPipelineFolderPermission','AzDoGroupEntitlement','AzDoServicePrincipalEntitlement','AzDoPicklist','AzDoProcessWorkItemType','AzDoProcessField','AzDoProcessState','AzDoProcessRule','AzDoProcessBehavior','AzDoPipelineAuthorization','AzDoEnvironmentKubernetesResource','AzDoEnvironmentVMResource','AzDoDeploymentGroupTarget','AzDoReleaseFolder','AzDoReleaseFolderPermission','AzDoReleaseDefinitionPermission','AzDoTestVariable','AzDoTestConfiguration','AzDoTestPlan','AzDoTestSuite','AzDoBuildRetentionSettings','AzDoWikiPage','AzDoTaggingPermission','AzDoAnalyticsPermission','AzDoAnalyticsViewsPermission','AzDoDashboard','AzDoOrganizationPermission','AzDoTaskGroupPermission') RequiredAssemblies = @() # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell. PrivateData = @{ PSData = @{ # Set to a prerelease string value if the release should be a prerelease. Prerelease = 'preview1' # Tags applied to this module. These help with module discovery in online galleries. Tags = @('DesiredStateConfiguration', 'DSC', 'DSCResourceKit', 'DSCResource', 'DSCv3', 'AzureDevOps') # A URL to the license for this module. LicenseUri = 'https://github.com/ZanattaMichael/AzureDevOpsDsc/blob/main/LICENSE' # A URL to the main website for this project. ProjectUri = 'https://github.com/ZanattaMichael/AzureDevOpsDsc' # A URL to an icon representing this module. IconUri = 'https://dsccommunity.org/images/DSC_Logo_300p.png' # ReleaseNotes of this module. # Per-release notes are generated from the CHANGELOG's [Unreleased] section # at build time and attached to the GitHub Release. This link is the fallback # shown on the Gallery listing. ReleaseNotes = '## [1.3.1-preview1] - 2026-11-13 ### Security - Credential storage - `New-AzDoAuthenticationProvider` no longer leaves `ModuleSettings.clixml` and the cache directory with default permissions. A new private helper, `Protect-AzDoCachePath`, restricts everything the module writes under `AZDODSC_CACHE_DIRECTORY` to its owner: on Windows the ACL is replaced with an explicit, non-inherited DACL granting FullControl to the current user, SYSTEM and BUILTIN\Administrators only; on Linux and macOS files are set to mode 600 and directories to 700. `New-AzDoAuthenticationProvider`, `Export-CacheObject`, `Initialize-CacheObject` and `Save-IdentityDescriptorIndex` apply it to every directory they create and file they write, so the identity caches and `IdentityDescriptorIndex.clixml`, which decide which identity a permission grant resolves to, are covered as well. A permissions failure is a warning, never an error. - On Linux and macOS `Export-Clixml` stores a SecureString as hex-encoded UTF-16, so `ModuleSettings.clixml` holds the credential in a recoverable form. `New-AzDoAuthenticationProvider` now warns on those platforms that the file is protected only by the owner-only permissions it sets, that `AZDODSC_CACHE_DIRECTORY` must be a private path, and that DSC must run as the same account. `USAGE.md` and `CLAUDE.md` describe this. - `New-AzDoAuthenticationProvider` defaults to the `SecureStringPersonalAccessToken` parameter set. The plain-text `-PersonalAccessToken` and `-ClientSecret` parameters still work but warn that the secret lands in shell history, transcripts and process listings, and name the `-SecureStringPersonalAccessToken` / `-SecureStringClientSecret` alternative. Every example and the integration test framework use the SecureString parameters. - Transport - `Invoke-AzDevOpsApiRestMethod` refuses any request that is not https before it builds an Authorization header. The only exceptions are the two instance metadata endpoints that answer http only: IMDS (`169.254.169.254`) and the Azure Arc agent on `localhost`. `Test-AzDevOpsApiUri` accepts https only. - Azure Arc - `Get-AzManagedIdentityToken` validates both Azure Arc inputs before using them, as Microsoft''s reference implementations do. `IDENTITY_ENDPOINT` must be an absolute http/https URI on `localhost`, `127.0.0.1` or `::1`; the secret file path from the 401 challenge (`WWW-Authenticate: Basic realm=<path>`) must be a `.key` file directly inside the Arc tokens directory (`%ProgramData%\AzureConnectedMachineAgent\Tokens` on Windows, `/var/opt/azcmagent/tokens` on Linux). Anything else throws, naming the value, before a request is sent or a file is read. New private helpers `Test-AzDoArcSecretFilePath` and `Get-AzDoArcTokensDirectory`. - Token guard - `AuthenticationToken.TestCaller()` no longer carries the `Write-*` and `Out-File` checks, which could never fire (`TestCallStack` compares whole command names, and arguments are evaluated before a cmdlet is on the stack). The comments above it and above `ServicePrincipalToken.GetClientSecret()` now say what the remaining call-stack check is: a guard against accidental use of the plain token outside the module''s request path, not a security boundary. The allowed-callers behaviour is unchanged. - Secrets in logs and exports - `AzDevOpsDscResourceBase` gains `FormatPropertiesForLog()`, which renders current-state properties for verbose logging with secret properties (those named by `GetDscResourceSecretPropertyNames()`) shown as `<redacted>` and hashtable-valued properties shown as key names only. `AzDoVariableGroup`, `AzDoServiceConnection`, `AzDoAuditStream` and `AzDoServiceHook` log through it, so variable values, a service connection''s `serviceprincipalkey` and consumer credentials no longer reach DSC verbose logs. - `AzDoServiceConnection` declares `Authorization`, and `AzDoAuditStream` and `AzDoServiceHook` declare `ConsumerInputs`, as secret properties, so `Export()` redacts them through `Protect-AzDoExportedSecretProperty` instead of writing them out. - `AzDoVariableGroup` can create secret variables: `Variables` accepts `@{ NAME = @{ value = ''v''; isSecret = $true } }` alongside `@{ NAME = ''value'' }`. A secret variable''s value is never read back, compared or logged. - CI - The integration test workflow no longer admits pull requests from forks. Both `integration-tests.yml` jobs require the pull request''s head repository to be this repository in addition to the `resource-add/` branch prefix, and the test framework configuration step refuses to fall back to Managed Identity on a `pull_request` run (it throws if `AZURE_DEVOPS_PAT` is empty). Previously a fork''s code could have run on the self-hosted runner under the runner VM''s identity. - Both integration workflows wipe the module cache directory before the run and, in a final `if: always()` step, remove it again and restore `tests/Integration/TestFrameworkConfiguration.json` from git, so neither `ModuleSettings.clixml` nor the plain-text PAT survives the job on the runner. - `publish.yml` token permissions moved from workflow level to job level; only the `publish` job holds `contents: write` and `pull-requests: write`; the release-gate jobs on the self-hosted runners get `contents: read`. - `actions/checkout`, `actions/cache` and `actions/upload-artifact` are pinned to commit SHAs (v4.4.0, v4.3.0, v4.6.2) in every workflow. - New `script-analysis` job in `unit-tests.yml` runs PSScriptAnalyzer 1.24.0 over `source/Classes`, `source/Modules` and `source/Enum` with the security-focused rule set in the new `PSScriptAnalyzerSettings.psd1`; any finding fails the job. ### Changed - Build - `Resolve-Dependency.psd1` pins `PSResourceGetVersion` to `1.2.0`. It was unset, so the bootstrap downloaded the newest PSResourceGet on every run, and with `1.3.1` the first `Save-PSResource` fails with `Response returned status code package: Not Found`, which stopped the build and unit test workflows before any module code ran. - Performance - `Find-Identity` scans the group, user and service-principal caches with a plain loop instead of invoking a filter scriptblock for every cached identity. It runs once per ACE, so this is the largest part of formatting an ACL: with 2,000 identities in each cache a lookup takes about a third of the time it did. What it returns, and what it warns about, is unchanged. - `ConvertTo-FormattedACL` resolves each ACE descriptor once per call rather than once per ACE. A namespace holds far more ACEs than distinct identities, so formatting 300 ACLs that share 20 identities went from about 7.5 seconds to under one. A descriptor that does not resolve is remembered for the rest of the call as well, so the ACEs a deleted identity leaves behind cost one API lookup and one warning per call instead of one for every ACE. - `AzDoAPI_3_GroupMemberCache` matches each group''s member descriptors through a set instead of testing every cached user and group against the member list with `-in`. Building the cache for 400 groups and 1,500 users went from 9.4 seconds to 0.75 (excluding the API calls), with the same members in the same order. - `AzureDevOpsDsc.Common` imports faster, which matters because DSC imports the module again for each resource invocation. The function files are enumerated with `System.IO` instead of `Get-ChildItem -Recurse -Include`, the public functions are exported in one `Export-ModuleMember` call instead of one call each, and the cache initializers, which two of the listed directories both reach, are dot-sourced once. The functions defined and exported are the same. - A resource instance keeps the authentication token its session already holds when that token is unexpired and was issued for the organization and identity in `ModuleSettings.clixml` (`[AzDevOpsDscResourceBase]::CanReuseAuthenticationToken()`). Until now every instance acquired a new one - a request to Microsoft Entra ID or the identity endpoint, or a new `az` process - so an export paid that for each exported instance. A personal access token is never kept this way, and a session that holds no token, such as the fresh runspace `Invoke-DscResource` starts, restores it exactly as before. - Documentation - `docs/ResourceRoadmap.md` gains §12, the resources a code review found missing that neither the roadmap nor an open issue tracked: permission resources for the `Collection`, `MetaTask`, `ServiceHooks`, `AuditLog`, `EventSubscription` and `VersionControlItems` namespaces and for deployment groups and project agent queues; `AzDoWorkItemTemplate` and `AzDoTaskboardColumn`; `AzDoAgent`, agent pool maintenance and per-pipeline settings on `AzDoPipeline`; `AzDoTestResultRetentionSettings` and organization-wide feed permissions; and project properties and notification delivery settings. It also records what was checked and found already covered or not buildable, and a suggested order. §2, §8 and §9 point to it. - `docs/ResourceRoadmap.md` gains §13 for open issues #66 (Copilot code review) and #67 (GitHub Advanced Security), which the roadmap did not mention. It lists the proposed resources and the questions each issue must settle first, and gives an order. §8 and §9 point to it. - Tests - The integration tests for `AzDoDashboard`, `AzDoOrganizationPermission` and `AzDoTaskGroupPermission` now read the live state back from the REST API after each `Set`, instead of relying only on the resource''s' } # End of PSData hashtable } # End of PrivateData hashtable } |