Home

Awesome

PSRule.Rules.AzureDevOps

PowerShell Gallery Version (excluding pre-releases) PowerShell Gallery GitHub Workflow Status (with event) codecov

PSRule Module for Azure DevOps

This powershell module is built to be used with Bernie White's excellent PSRule module to check an Azure DevOps project for best practices for a secure development environment. The module takes best practices from the official Azure DevOps Security best practices documentation. It can function as a periodic security scan and check for your Azure DevOps project.

This module is actively developed since August 2023. Although a lot of testing has been performed and is built in to the development cycle, up to now little feedback has come back from the community yet. Any input on the direction of the module and included rules is very much appreciated. Please consider opening an issue with your ideas, encountered problems in using the module or other contributions. Any feedback is highly appreciated.

Screenshot of version 0.0.11 Sarif output in Azure DevOps

Easy to use spin-off project

If you are looking for an easy to use spin-off project that uses this module and gives you a nice dashboard in Azure Monitor, please have a look at the PsrAzDo-workbooks project. It is a set of Azure Monitor Workbooks that can be used to visualize the results of the PSRule.Rules.AzureDevOps module. The workbooks are easily deployed through through the included Bicep template and modules. A Yaml pipeline is included to run the PSRule.Rules.AzureDevOps module on a daily basis and upload the results to Azure Monitor.

Usage

To use this module, you need to have PSRule installed. You can install it from the PowerShell Gallery:

Install-Module -Name PSRule -Scope CurrentUser

Once you have PSRule installed, you can install this module from the PowerShell Gallery:

Install-Module -Name PSRule.Rules.AzureDevOps -Scope CurrentUser

PAT Token

Once you have both modules installed, you can connect to your Azure DevOps organization and run an export of your Azure DevOps project and run the rules on the exported data. The -PAT value needs to be an Azure DevOps Personal Access Token with sufficient permissions to read the project data. The default expects a PAT with full access permissions. Alternately, you can use a PAT with only read permissions or fine-grained permissions with the -TokenType parameter. The fine-grained permissions expect read access to all scopes and read & manage for scope that do not have read-only access. Documentation on how to create the PATs can be found in the docs/token-permissions.md.

Example: Run with full access token

Connect-AzDevOps `
    -Organization "MyOrg" `
    -PAT $MyPAT
Export-AzDevOpsRuleData `
    -Project "MyProject" `
    -OutputPath "C:\Temp\MyProject"
Assert-PSRule `
    -InputPath "C:\Temp\MyProject\" `
    -Module PSRule.Rules.AzureDevOps

Example: Run with read-only access token

Connect-AzDevOps `
    -Organization "MyOrg" `
    -PAT $MyPAT `
    -TokenType ReadOnly
Export-AzDevOpsRuleData `
    -Project "MyProject" `
    -OutputPath "C:\Temp\MyProject"
Assert-PSRule `
    -InputPath "C:\Temp\MyProject\" `
    -Module PSRule.Rules.AzureDevOps

Service Principal or Managed Identity

Since version 0.3.0 of this module, you can also connect to your Azure DevOps organization with a Service Principal or Managed Identity. The -AuthType parameter can be set to ServicePrincipal or ManagedIdentity. The Service Principal needs to have sufficient permissions to read the project data. The default expects a Service Principal with project administrator permissions. Alternately, you can use a Service Principal with only read permissions or fine-grained permissions with the -TokenType parameter.

Example: Run with a Service Principal

Connect-AzDevOps `
    -Organization "MyOrg" `
    -AuthType ServicePrincipal `
    -ClientId $MyAppId `
    -ClientSecret $MyAppSecret `
    -TenantId $MyTenantId
Export-AzDevOpsRuleData `
    -Project "MyProject" `
    -OutputPath "C:\Temp\MyProject"
Assert-PSRule `
    -InputPath "C:\Temp\MyProject\" `
    -Module PSRule.Rules.AzureDevOps

Example: Run with a System Assigned Managed Identity

Connect-AzDevOps `
    -Organization "MyOrg" `
    -AuthType ManagedIdentity
Export-AzDevOpsRuleData `
    -Project "MyProject" `
    -OutputPath "C:\Temp\MyProject"
Assert-PSRule `
    -InputPath "C:\Temp\MyProject\" `
    -Module PSRule.Rules.AzureDevOps

Example: Run with a User Assigned Managed Identity

$env:ADO_MSI_CLIENT_ID = $MyClientId
Connect-AzDevOps `
    -Organization "MyOrg" `
    -AuthType ManagedIdentity `
Export-AzDevOpsRuleData `
    -Project "MyProject" `
    -OutputPath "C:\Temp\MyProject"
Assert-PSRule `
    -InputPath "C:\Temp\MyProject\" `
    -Module PSRule.Rules.AzureDevOps

Screenshot of version 0.0.9 run

Organization level export

Since version 0.0.8 of this module, you can also export the data at the organization level, looping through all projects in the organization the PAT has access to.

Export-AzDevOpsOrganizationRuleData `
    -OutputPath "C:\Temp\MyOrg"

Disable checks for Azure DevOps Features that require additional licenses

Since version 0.0.12 of this module, you can disable rules that check for Azure DevOps features that require additional licenses. This is done through applying the Baseline.NoExtraLicense baseline to the Assert-PSRule command through the -Baseline option.

Assert-PSRule `
    -InputPath "C:\Temp\MyProject\" `
    -Module PSRule.Rules.AzureDevOps `
    -Baseline Baseline.NoExtraLicense

Rules

Documentation for the implemented rules can be found in the en folder in the module folder.

This annotated version of the official security best practices provides a reference for how the rules in this module are related to the best practices recommended by Microsoft. It is the main guiding document in building the ruleset for this module.

Implemented rules

Contributing

This project welcomes contributions and suggestions. Please read CONTRIBUTING.md for details on how to contribute.

License

This project is licensed under the MIT License.

Acknowledgements

Maintainer

References