Skip to content

Home

Jump to bottom
github-actions edited this page Dec 10, 2023 · 16 revisions

PSRule.Rules.AzureDevOps

PowerShell Gallery Version (including 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 very much in early stage of development and should not be considered stable. Any input on the direction of the module and included rules is very much appreciated. Please consider opening an issue with your ideas.

Screenshot of version 0.0.11 Sarif output in Azure DevOps

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.

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

Clone this wiki locally