Azure / Azure/azure-powershell

[AzPS] Remediate existing GUID / sensitive identifier violations and add CI validation to prevent reintroduction

Open
#29,951 0 comments 0 reactions 0 assignees View on GitHub
bug Doc - Reference feature-request
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.