microsoft / microsoft/hve-core
docs: update scripts/security/README.md to document Test-PSModulePins.ps1 and ps-module-versions.json
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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