microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
scripts/security/Modules/SecurityClasses.psm1
148lines · modecode
| 1 | # Copyright (c) Microsoft Corporation. |
| 2 | # SPDX-License-Identifier: MIT |
| 3 | |
| 4 | # SecurityClasses.psm1 |
| 5 | # |
| 6 | # Purpose: Shared class definitions for security scanning scripts. |
| 7 | # Author: HVE Core Team |
| 8 | |
| 9 | <# |
| 10 | .SYNOPSIS |
| 11 | Shared class definitions for dependency pinning and compliance reporting. |
| 12 | |
| 13 | .DESCRIPTION |
| 14 | This module contains class definitions used by security scanning scripts: |
| 15 | - DependencyViolation: Represents a single dependency pinning violation |
| 16 | - ComplianceReport: Aggregates violations and generates compliance reports |
| 17 | |
| 18 | .NOTES |
| 19 | Classes must be imported using 'using module' syntax at the top of scripts: |
| 20 | using module ./Modules/SecurityClasses.psm1 |
| 21 | #> |
| 22 | |
| 23 | class DependencyViolation { |
| 24 | <# |
| 25 | .SYNOPSIS |
| 26 | Represents a single dependency pinning violation. |
| 27 | |
| 28 | .DESCRIPTION |
| 29 | Contains information about a dependency that is not properly pinned, |
| 30 | including file location, dependency details, and remediation guidance. |
| 31 | |
| 32 | ViolationType values: |
| 33 | - Unpinned: Dependency is not pinned to an immutable reference |
| 34 | - Stale: Pinned dependency has a newer version available |
| 35 | - VersionMismatch: Version comment does not match the resolved pinned reference |
| 36 | - MissingVersionComment: Dependency is pinned but lacks a human-readable version comment |
| 37 | - MissingPermissions: Workflow file lacks required permissions declarations |
| 38 | - Empty string: Default or unclassified violation |
| 39 | #> |
| 40 | |
| 41 | [string]$File |
| 42 | [int]$Line |
| 43 | [string]$Type |
| 44 | [string]$Name |
| 45 | [string]$Version |
| 46 | [string]$CurrentRef |
| 47 | [string]$Severity |
| 48 | [ValidateSet('Unpinned', 'Stale', 'VersionMismatch', 'MissingVersionComment', 'MissingPermissions', '')] |
| 49 | [string]$ViolationType |
| 50 | [string]$Description |
| 51 | [string]$Remediation |
| 52 | [hashtable]$Metadata |
| 53 | |
| 54 | DependencyViolation() { |
| 55 | $this.Metadata = @{} |
| 56 | } |
| 57 | |
| 58 | DependencyViolation( |
| 59 | [string]$File, |
| 60 | [int]$Line, |
| 61 | [string]$Type, |
| 62 | [string]$Name, |
| 63 | [string]$Severity, |
| 64 | [string]$Description |
| 65 | ) { |
| 66 | $this.File = $File |
| 67 | $this.Line = $Line |
| 68 | $this.Type = $Type |
| 69 | $this.Name = $Name |
| 70 | $this.Severity = $Severity |
| 71 | $this.Description = $Description |
| 72 | $this.Metadata = @{} |
| 73 | } |
| 74 | } |
| 75 | |
| 76 | class ComplianceReport { |
| 77 | <# |
| 78 | .SYNOPSIS |
| 79 | Aggregates dependency violations and generates compliance reports. |
| 80 | |
| 81 | .DESCRIPTION |
| 82 | Collects violations from dependency scans and provides metrics like |
| 83 | compliance score, total dependencies, and summary by type. |
| 84 | #> |
| 85 | |
| 86 | [string]$ScanPath |
| 87 | [datetime]$Timestamp |
| 88 | [int]$TotalFiles |
| 89 | [int]$ScannedFiles |
| 90 | [int]$TotalDependencies |
| 91 | [int]$PinnedDependencies |
| 92 | [int]$UnpinnedDependencies |
| 93 | [decimal]$ComplianceScore |
| 94 | [DependencyViolation[]]$Violations |
| 95 | [hashtable]$Summary |
| 96 | [hashtable]$Metadata |
| 97 | |
| 98 | ComplianceReport() { |
| 99 | $this.Timestamp = Get-Date |
| 100 | $this.Violations = @() |
| 101 | $this.Summary = @{} |
| 102 | $this.Metadata = @{} |
| 103 | } |
| 104 | |
| 105 | ComplianceReport([string]$ScanPath) { |
| 106 | $this.ScanPath = $ScanPath |
| 107 | $this.Timestamp = Get-Date |
| 108 | $this.Violations = @() |
| 109 | $this.Summary = @{} |
| 110 | $this.Metadata = @{} |
| 111 | } |
| 112 | |
| 113 | [void] AddViolation([DependencyViolation]$Violation) { |
| 114 | $this.Violations += $Violation |
| 115 | $this.UnpinnedDependencies = $this.Violations.Count |
| 116 | } |
| 117 | |
| 118 | [void] CalculateScore() { |
| 119 | if ($this.TotalDependencies -gt 0) { |
| 120 | $this.ComplianceScore = [math]::Round( |
| 121 | ($this.PinnedDependencies / $this.TotalDependencies) * 100, 2 |
| 122 | ) |
| 123 | } |
| 124 | else { |
| 125 | $this.ComplianceScore = 100.0 |
| 126 | } |
| 127 | } |
| 128 | |
| 129 | [hashtable] ToHashtable() { |
| 130 | return @{ |
| 131 | ScanPath = $this.ScanPath |
| 132 | Timestamp = $this.Timestamp.ToString('yyyy-MM-ddTHH:mm:ss.fffZ') |
| 133 | TotalFiles = $this.TotalFiles |
| 134 | ScannedFiles = $this.ScannedFiles |
| 135 | TotalDependencies = $this.TotalDependencies |
| 136 | PinnedDependencies = $this.PinnedDependencies |
| 137 | UnpinnedDependencies = $this.UnpinnedDependencies |
| 138 | ComplianceScore = $this.ComplianceScore |
| 139 | Violations = $this.Violations |
| 140 | Summary = $this.Summary |
| 141 | Metadata = $this.Metadata |
| 142 | } |
| 143 | } |
| 144 | } |
| 145 | |
| 146 | # Classes are exported automatically when imported via 'using module' syntax. |
| 147 | # No functions to export. |
| 148 | Export-ModuleMember -Function @() |
| 149 | |