Azure / Azure/azure-powershell
[AzPS] Remediate existing GUID / sensitive identifier violations and add CI validation to prevent reintroduction
- Dominant language
- C#
- Stars
- 4.8k
- Forks
- 4.3k
- Avg merge
- 2d 17h
- Merged PRs (30d)
- 51
Description
### Description
## Background
During the Docs Sync discussion, we identified recurring documentation updates related to GUID and sensitive identifier compliance.
Microsoft guidance:
- Sensitive Identifier Reference
https://learn.microsoft.com/en-us/help/platform/reference-sensitive-identifier
The issue currently requires repeated downstream documentation fixes. However, the violations continue to reappear because the source content is not corrected and there is no validation preventing new violations from being introduced.
## Evidence
The Docs team has repeatedly submitted SFI remediation pull requests to address the same class of issues.
Historical examples:
- MicrosoftDocs/azure-docs-powershell Bundle-Security PRs
https://github.com/MicrosoftDocs/azure-docs-powershell/pulls?q=is%3Apr+Bundle-Security+is%3Aclosed
As discussed, fixing generated markdown files is only a temporary mitigation because future generations can overwrite those fixes.
## Problem Statement
GUIDs, subscription IDs, tenant IDs, object IDs, and other sensitive identifiers are being propagated into documentation from upstream source content.
This results in:
- Recurring SFI remediation work
- Repeated documentation cleanup PRs
- Additional operational overhead for Docs and Engineering teams
- Compliance issues appearing release after release
## Proposed Solution
### Phase 1: One-time Source Remediation
Perform a repository-wide audit and remediate existing violations at the source.
Review and clean up identifiers in:
- Source code examples
- Help content
- Test assets
- Documentation source files
- Generated content inputs
- Command metadata
Replace non-compliant values with approved identifiers according to Microsoft guidance.
### Phase 2: Add CI Guardrails
Introduce automated validation in Azure PowerShell (and other applicable repositories) to detect non-compliant identifiers during pull request validation and CI builds.
Validation should:
- Run on every PR
- Run in official CI pipelines
- Detect unapproved GUIDs and sensitive identifiers
- Fail validation when violations are detected
- Provide actionable remediation guidance
The goal is to ensure that developers cannot merge PRs containing non-compliant identifiers and that the issue is prevented before documentation generation.
## Expected Outcome
- Existing violations are removed from source.
- Documentation generation no longer reintroduces known violations.
- Future violations are blocked during PR validation.
- Recurring SFI cleanup effort is significantly reduced.
## References
- Sensitive Identifier Reference
https://learn.microsoft.com/en-us/help/platform/reference-sensitive-identifier
- Historical SFI Remediation PRs
https://github.com/MicrosoftDocs/azure-docs-powershell/pulls?q=is%3Apr+Bundle-Security+is%3Aclosed
``
### Issue script & Debug output
```PowerShell
Doc issue
```
### Environment data
```PowerShell
PS7.0
```
### Module versions
```PowerShell
Az
```
### Error output
```PowerShell
```
Contributor guide
Research direction
Start by auditing the source code examples, help content, test assets, documentation source files, generated content inputs, and command metadata named in the issue. Review the Sensitive Identifier Reference and historical Bundle-Security pull requests, then determine how PR and official CI validation should cover those sources. Done means existing violations are remediated and future non-compliant identifiers fail validation with actionable guidance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, powershell
- Domain
- ci-cd, documentation, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100