microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
scripts/security/README.md
221lines · 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: 2025-11-05 |
| 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 SHA 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 | ## Modules |
| 184 | |
| 185 | ### `Modules/SecurityClasses.psm1` |
| 186 | |
| 187 | Shared class definitions imported using `using module` syntax: |
| 188 | |
| 189 | | Class | Purpose | |
| 190 | |-----------------------|-------------------------------------------------------------------------| |
| 191 | | `DependencyViolation` | Tracks individual pinning violations with file location and remediation | |
| 192 | | `ComplianceReport` | Aggregates violations and calculates compliance scores | |
| 193 | |
| 194 | ### `Modules/SecurityHelpers.psm1` |
| 195 | |
| 196 | Shared utility functions used across security scripts: |
| 197 | |
| 198 | | Function | Purpose | |
| 199 | |---------------------|---------------------------------------------------------------------------| |
| 200 | | `Write-SecurityLog` | Outputs timestamped, color-coded log entries with optional CI annotations | |
| 201 | |
| 202 | ## GitHub Actions Integration |
| 203 | |
| 204 | Security scripts integrate with these workflows: |
| 205 | |
| 206 | | Workflow | Script(s) | Trigger | |
| 207 | |-------------------------------|------------------------------|--------------| |
| 208 | | `dependency-pinning-scan.yml` | `Test-DependencyPinning.ps1` | PR, schedule | |
| 209 | | `sha-staleness-check.yml` | `Test-SHAStaleness.ps1` | Schedule | |
| 210 | | `pr-validation.yml` | `Test-DependencyPinning.ps1` | Pull request | |
| 211 | |
| 212 | ## Related Documentation |
| 213 | |
| 214 | * [Scripts README](../README.md) for overall script organization |
| 215 | * [Build Workflows](../../docs/architecture/workflows.md) for CI pipeline |
| 216 | details |
| 217 | |
| 218 | <!-- markdownlint-disable MD036 --> |
| 219 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 220 | then carefully refined by our team of discerning human reviewers.* |
| 221 | <!-- markdownlint-enable MD036 --> |
| 222 | |