microsoft / microsoft/hve-core

docs: update scripts/security/README.md to document Test-PSModulePins.ps1 and ps-module-versions.json

Open Beginner friendly
#1,435 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation stale-docs
Dominant language
Python
Stars
1.5k
Forks
301
Avg merge
3d 3h
Merged PRs (30d)
92

Description

## Component

Documentation

## Bug Description

`scripts/security/README.md` does not document `Test-PSModulePins.ps1` or `ps-module-versions.json`, both introduced in PR #1378 (`fix(ci): pin PowerShell-Yaml to 0.4.7 across all install sites`).

The README documents all other security scripts (`Test-DependencyPinning.ps1`, `Test-SHAStaleness.ps1`, `Test-ActionVersionConsistency.ps1`, `Update-ActionSHAPinning.ps1`, `Invoke-PipAudit.ps1`, `Test-WorkflowPermissions.ps1`) but is missing a section for the new PS module pin checker.

## Expected Behavior

`scripts/security/README.md` should include a `### Test-PSModulePins.ps1` section describing:

- **Purpose**: Validates that all `Install-Module -Name -RequiredVersion ` calls across tracked repository files match the canonical versions declared in `scripts/security/ps-module-versions.json`.
- **Features**: Scans workflow YAML files and shell scripts for `Install-Module` calls, compares against `ps-module-versions.json`, and reports mismatches.
- **Parameters**: At minimum `-RepoRoot`, `-OutputPath`, and any soft-fail flags.
- **Usage**: The `npm run lint:ps-module-pins` command.

It should also document `ps-module-versions.json` as the canonical pin configuration file (alongside `tool-checksums.json` in the Architecture section).

## Steps to Reproduce

1. Review PR #1378 — `scripts/security/Test-PSModulePins.ps1` and `scripts/security/ps-module-versions.json` were added.
2. Open `scripts/security/README.md` — no section for `Test-PSModulePins.ps1` or `ps-module-versions.json` exists.
3. Run `cat scripts/security/README.md | grep PSModulePins` — returns no output.

## Additional Context

- Stale documentation: [`scripts/security/README.md`](https://github.com/microsoft/hve-core/blob/main/scripts/security/README.md) — Scripts section
- New script: [`scripts/security/Test-PSModulePins.ps1`](https://github.com/microsoft/hve-core/blob/main/scripts/security/Test-PSModulePins.ps1)
- New config: [`scripts/security/ps-module-versions.json`](https://github.com/microsoft/hve-core/blob/main/scripts/security/ps-module-versions.json)
- Introducing commit: PR #1378

> Generated by [Documentation Update Check](https://github.com/microsoft/hve-core/actions/runs/24857987575/agentic_workflow) · ● 4.8M · [◷](https://github.com/search?q=repo%3Amicrosoft%2Fhve-core+is%3Aissue+%22gh-aw-workflow-call-id%3A+microsoft%2Fhve-core%2Fdoc-update-check%22&type=issues)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with scripts/security/README.md, then read scripts/security/Test-PSModulePins.ps1 and scripts/security/ps-module-versions.json to accurately document the checker’s purpose, parameters, and canonical configuration. Update the Scripts and Architecture sections, and verify the references and npm run lint:ps-module-pins usage are present.

Written by the indexing model from the issue text.

Assessment

Tech stack
powershell
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
82/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.