microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
scripts/security/README.md
294lines · modecode
| 1 | --- |
| 2 | title: Security Scripts |
| 3 | description: PowerShell scripts for dependency pinning validation, SHA staleness monitoring, and supply chain security |
| 4 | author: HVE Core Team |
| 5 | ms.date: 2026-03-17 |
| 6 | ms.topic: reference |
| 7 | keywords: |
| 8 | - powershell |
| 9 | - security |
| 10 | - dependency-pinning |
| 11 | - sha-validation |
| 12 | - supply-chain |
| 13 | estimated_reading_time: 8 |
| 14 | --- |
| 15 | |
| 16 | This directory contains PowerShell scripts for validating dependency pinning |
| 17 | compliance, monitoring SHA staleness, and maintaining supply chain security in |
| 18 | the `hve-core` repository. |
| 19 | |
| 20 | ## Architecture |
| 21 | |
| 22 | The security scripts share common modules and follow a consistent pattern: |
| 23 | |
| 24 | * `SecurityClasses.psm1` defines shared data types for violation tracking and |
| 25 | compliance reporting |
| 26 | * `SecurityHelpers.psm1` provides timestamped logging, CI annotations, and file |
| 27 | output utilities |
| 28 | * `CIHelpers.psm1` (from `scripts/lib/`) provides CI platform detection and |
| 29 | GitHub Actions output formatting |
| 30 | * `tool-checksums.json` stores SHA256 checksums for verified tool downloads |
| 31 | |
| 32 | ## Scripts |
| 33 | |
| 34 | ### `Test-DependencyPinning.ps1` |
| 35 | |
| 36 | Verifies dependency pinning compliance for all dependencies in GitHub Actions workflows. |
| 37 | |
| 38 | Purpose: Detect unpinned or improperly pinned dependencies to maintain |
| 39 | supply chain security. |
| 40 | |
| 41 | #### Features |
| 42 | |
| 43 | * Scans workflow files for GitHub Actions, Docker images, and other dependency |
| 44 | types |
| 45 | * Categorizes violations by type (Unpinned, Stale, VersionMismatch, |
| 46 | MissingVersionComment) |
| 47 | * Outputs results in JSON, SARIF, CSV, Markdown, or table format |
| 48 | * Supports auto-remediation with `-Remediate` |
| 49 | * Configurable compliance threshold |
| 50 | |
| 51 | #### Parameters |
| 52 | |
| 53 | * `-Path` - Root path to scan (defaults to repository root) |
| 54 | * `-Recursive` (switch) - Scan subdirectories |
| 55 | * `-Format` - Output format: `json`, `sarif`, `csv`, `markdown`, `table` |
| 56 | * `-OutputPath` - File path for results output |
| 57 | * `-FailOnUnpinned` (switch) - Exit with non-zero code when violations exist |
| 58 | * `-ExcludePaths` - Paths to exclude from scanning |
| 59 | * `-IncludeTypes` - Dependency types to include |
| 60 | * `-Threshold` - Minimum compliance percentage |
| 61 | * `-Remediate` (switch) - Attempt automatic remediation |
| 62 | |
| 63 | #### Usage |
| 64 | |
| 65 | ```powershell |
| 66 | # Scan all workflows with table output |
| 67 | ./scripts/security/Test-DependencyPinning.ps1 -Recursive |
| 68 | |
| 69 | # Export SARIF results |
| 70 | ./scripts/security/Test-DependencyPinning.ps1 -Format sarif -OutputPath logs/pinning.sarif |
| 71 | |
| 72 | # Fail CI when unpinned dependencies exist |
| 73 | ./scripts/security/Test-DependencyPinning.ps1 -FailOnUnpinned -Recursive |
| 74 | ``` |
| 75 | |
| 76 | ### `Test-SHAStaleness.ps1` |
| 77 | |
| 78 | Monitors SHA-pinned dependencies for staleness by checking whether newer |
| 79 | versions are available. |
| 80 | |
| 81 | Purpose: Identify pinned dependencies that have fallen behind upstream |
| 82 | releases. |
| 83 | |
| 84 | #### Features |
| 85 | |
| 86 | * Queries GitHub API for latest releases of pinned actions |
| 87 | * Supports multiple output formats (JSON, Azure DevOps, GitHub, console) |
| 88 | * Configurable maximum age threshold |
| 89 | * Batch GraphQL queries for efficient API usage |
| 90 | |
| 91 | #### Parameters |
| 92 | |
| 93 | * `-OutputFormat` - Output format: `json`, `azdo`, `github`, `console` |
| 94 | * `-MaxAge` - Maximum age in days before a pin is considered stale |
| 95 | * `-LogPath` - Path for log file output |
| 96 | * `-OutputPath` - Path for structured results output |
| 97 | * `-FailOnStale` (switch) - Exit with non-zero code when stale pins exist |
| 98 | * `-GraphQLBatchSize` - Number of repositories per GraphQL batch query |
| 99 | |
| 100 | #### Usage |
| 101 | |
| 102 | ```powershell |
| 103 | # Check for stale SHAs with console output |
| 104 | ./scripts/security/Test-SHAStaleness.ps1 -OutputFormat console |
| 105 | |
| 106 | # Export JSON results with 90-day threshold |
| 107 | ./scripts/security/Test-SHAStaleness.ps1 -OutputFormat json -OutputPath logs/staleness.json -MaxAge 90 |
| 108 | |
| 109 | # Fail CI on stale dependencies |
| 110 | ./scripts/security/Test-SHAStaleness.ps1 -FailOnStale |
| 111 | ``` |
| 112 | |
| 113 | ### `Test-ActionVersionConsistency.ps1` |
| 114 | |
| 115 | Validates that GitHub Actions version comments match their corresponding SHA |
| 116 | pins across workflow files. |
| 117 | |
| 118 | Purpose: Detect mismatches between version comments and pinned SHAs that |
| 119 | could indicate incomplete updates. |
| 120 | |
| 121 | #### Features |
| 122 | |
| 123 | * Compares version comment annotations with resolved SHA references |
| 124 | * Outputs results in table, JSON, or SARIF format |
| 125 | * Integrates with `lint:version-consistency` npm script |
| 126 | |
| 127 | #### Parameters |
| 128 | |
| 129 | * `-Path` - Root path containing workflow files |
| 130 | * `-Format` - Output format: `Table`, `Json`, `Sarif` |
| 131 | * `-OutputPath` - File path for results output |
| 132 | * `-FailOnMismatch` (switch) - Exit with non-zero code when mismatches exist |
| 133 | * `-FailOnMissingComment` (switch) - Fail when SHA pins lack version comments |
| 134 | |
| 135 | #### Usage |
| 136 | |
| 137 | ```powershell |
| 138 | # Check version consistency |
| 139 | ./scripts/security/Test-ActionVersionConsistency.ps1 |
| 140 | |
| 141 | # Fail on mismatches (used in CI) |
| 142 | ./scripts/security/Test-ActionVersionConsistency.ps1 -FailOnMismatch |
| 143 | |
| 144 | # Export JSON results |
| 145 | ./scripts/security/Test-ActionVersionConsistency.ps1 -Format Json -OutputPath logs/version-consistency.json |
| 146 | ``` |
| 147 | |
| 148 | ### `Update-ActionSHAPinning.ps1` |
| 149 | |
| 150 | Updates GitHub Actions workflow files to use SHA-pinned references. Supports |
| 151 | `WhatIf` via `SupportsShouldProcess`. |
| 152 | |
| 153 | Purpose: Automate the process of resolving and updating SHA pins for GitHub |
| 154 | Actions dependencies. |
| 155 | |
| 156 | #### Features |
| 157 | |
| 158 | * Resolves current SHA for each action reference |
| 159 | * Supports dry-run via `-WhatIf` |
| 160 | * Updates stale pins with `-UpdateStale` |
| 161 | * Generates update reports |
| 162 | |
| 163 | #### Parameters |
| 164 | |
| 165 | * `-WorkflowPath` - Path to workflow file(s) to update |
| 166 | * `-OutputReport` - Path for the update report |
| 167 | * `-OutputFormat` - Report format |
| 168 | * `-UpdateStale` (switch) - Update only stale pins rather than all |
| 169 | |
| 170 | #### Usage |
| 171 | |
| 172 | ```powershell |
| 173 | # Preview changes without modifying files |
| 174 | ./scripts/security/Update-ActionSHAPinning.ps1 -WhatIf |
| 175 | |
| 176 | # Update all SHA pins |
| 177 | ./scripts/security/Update-ActionSHAPinning.ps1 |
| 178 | |
| 179 | # Update stale pins and generate report |
| 180 | ./scripts/security/Update-ActionSHAPinning.ps1 -UpdateStale -OutputReport logs/sha-update-report.json |
| 181 | ``` |
| 182 | |
| 183 | ### `Invoke-PipAudit.ps1` |
| 184 | |
| 185 | Audits Python project dependencies for known vulnerabilities using pip-audit. |
| 186 | |
| 187 | Purpose: Detect vulnerable Python packages across all Python skills before they |
| 188 | reach production. |
| 189 | |
| 190 | #### Features |
| 191 | |
| 192 | * Discovers Python projects via `pyproject.toml` file search |
| 193 | * Exports locked dependencies via `uv export` before auditing |
| 194 | * Runs pip-audit against each project's dependency set |
| 195 | * Writes JSON results to the `logs/` directory |
| 196 | * Configurable path exclusions |
| 197 | |
| 198 | #### Parameters |
| 199 | |
| 200 | * `-Path` - Root path to scan for Python projects (default: repository root) |
| 201 | * `-OutputPath` - Directory for JSON results (default: `logs/` under repository root) |
| 202 | * `-FailOnVulnerability` (switch) - Exit with error code if vulnerabilities are found |
| 203 | * `-ExcludePaths` - Path patterns to exclude from scanning |
| 204 | |
| 205 | #### Usage |
| 206 | |
| 207 | ```powershell |
| 208 | # Scan all Python projects |
| 209 | ./scripts/security/Invoke-PipAudit.ps1 |
| 210 | |
| 211 | # Fail if vulnerabilities found |
| 212 | ./scripts/security/Invoke-PipAudit.ps1 -FailOnVulnerability |
| 213 | |
| 214 | # Scan a specific skill directory |
| 215 | ./scripts/security/Invoke-PipAudit.ps1 -Path ".github/skills/experimental/powerpoint" |
| 216 | ``` |
| 217 | |
| 218 | ### `Test-WorkflowPermissions.ps1` |
| 219 | |
| 220 | Validates that GitHub Actions workflow files include a top-level `permissions` block. |
| 221 | |
| 222 | Purpose: Ensure workflows explicitly declare token permissions to prevent |
| 223 | OpenSSF Scorecard Token-Permissions failures. |
| 224 | |
| 225 | #### Features |
| 226 | |
| 227 | * Scans `.github/workflows/*.yml` and `.yaml` files |
| 228 | * Uses regex-based detection (`^permissions:`) with zero false positives |
| 229 | * Outputs results in JSON, SARIF, or console format |
| 230 | * Configurable workflow exclusions |
| 231 | * Integrates with `npm run lint:permissions` |
| 232 | |
| 233 | #### Parameters |
| 234 | |
| 235 | * `-Path` - Directory containing workflow YAML files (default: `.github/workflows`) |
| 236 | * `-Format` - Output format: `json`, `sarif`, or `console` (default: `json`) |
| 237 | * `-OutputPath` - Path for result output file (default: `logs/workflow-permissions-results.json`) |
| 238 | * `-FailOnViolation` (switch) - Exit with non-zero code if any workflow is missing permissions |
| 239 | * `-ExcludePaths` - Workflow filenames to exclude (default: `copilot-setup-steps.yml`) |
| 240 | |
| 241 | #### Usage |
| 242 | |
| 243 | ```powershell |
| 244 | # Check all workflows |
| 245 | ./scripts/security/Test-WorkflowPermissions.ps1 |
| 246 | |
| 247 | # Fail on missing permissions |
| 248 | ./scripts/security/Test-WorkflowPermissions.ps1 -FailOnViolation |
| 249 | |
| 250 | # Export SARIF results |
| 251 | ./scripts/security/Test-WorkflowPermissions.ps1 -Format sarif -FailOnViolation |
| 252 | ``` |
| 253 | |
| 254 | ## Modules |
| 255 | |
| 256 | ### `Modules/SecurityClasses.psm1` |
| 257 | |
| 258 | Shared class definitions imported using `using module` syntax: |
| 259 | |
| 260 | | Class | Purpose | |
| 261 | |-----------------------|-------------------------------------------------------------------------| |
| 262 | | `DependencyViolation` | Tracks individual pinning violations with file location and remediation | |
| 263 | | `ComplianceReport` | Aggregates violations and calculates compliance scores | |
| 264 | |
| 265 | ### `Modules/SecurityHelpers.psm1` |
| 266 | |
| 267 | Shared utility functions used across security scripts: |
| 268 | |
| 269 | | Function | Purpose | |
| 270 | |---------------------|---------------------------------------------------------------------------| |
| 271 | | `Write-SecurityLog` | Outputs timestamped, color-coded log entries with optional CI annotations | |
| 272 | |
| 273 | ## GitHub Actions Integration |
| 274 | |
| 275 | Security scripts integrate with these workflows: |
| 276 | |
| 277 | | Workflow | Script(s) | Trigger | |
| 278 | |---------------------------------|--------------------------------|--------------| |
| 279 | | `dependency-pinning-scan.yml` | `Test-DependencyPinning.ps1` | PR, schedule | |
| 280 | | `sha-staleness-check.yml` | `Test-SHAStaleness.ps1` | Schedule | |
| 281 | | `pr-validation.yml` | `Test-DependencyPinning.ps1` | Pull request | |
| 282 | | `pip-audit.yml` | `Invoke-PipAudit.ps1` | PR, schedule | |
| 283 | | `workflow-permissions-scan.yml` | `Test-WorkflowPermissions.ps1` | PR, schedule | |
| 284 | |
| 285 | ## Related Documentation |
| 286 | |
| 287 | * [Scripts README](../README.md) for overall script organization |
| 288 | * [Build Workflows](../../docs/architecture/workflows.md) for CI pipeline |
| 289 | details |
| 290 | |
| 291 | <!-- markdownlint-disable MD036 --> |
| 292 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 293 | then carefully refined by our team of discerning human reviewers.* |
| 294 | <!-- markdownlint-enable MD036 --> |
| 295 | |