src/assess/engine/Get-RuleSet.ps1
|
#Requires -Version 7.0 Set-StrictMode -Version Latest $ErrorActionPreference = 'Stop' # Parsed rule documents keyed by file path + size + write time (see Get-RuleSet). Reset whenever this # file is loaded, so a re-imported module starts empty. $script:ScoutRuleDocumentCache = @{} <# .SYNOPSIS Load rule files matching the supplied glob patterns. .PARAMETER Overrides Optional hashtable of ruleId -> override, sourced from a Scout config file (Import-ScoutConfig's RuleOverrides, AB#373/#375). Each entry either: - is a bare scalar, applied as the rule's new `assert.value` (the common "threshold override" case, e.g. loosen/tighten a countLessThan bound), or - is a hashtable/pscustomobject with a `value` and/or `type` key, applied onto the rule's existing `assert.value` / `assert.type` respectively. Rule ids absent from Overrides, or rules with no `assert` block (manual rules), are left untouched. A $null/empty map is a no-op. .NOTES Requires the powershell-yaml module. Tracks ADO Story AB#5028. #> function Get-RuleSet { param([string[]] $Patterns, [hashtable] $Overrides) Import-Module powershell-yaml -ErrorAction Stop $ruleDir = "$PSScriptRoot/../rules" # A plain loop, not `Get-ChildItem | Where-Object { $Patterns | Where-Object ... }`: that nested # pipeline cost ~35 ms per call (44 rule files), paid once per assessment. Same wildcard # semantics (-like, case-insensitive, any pattern matches) and the same directory order. $files = foreach ($candidate in (Get-ChildItem $ruleDir -Filter *.yaml)) { $baseName = $candidate.BaseName foreach ($pattern in $Patterns) { if ($baseName -like $pattern) { $candidate; break } } } # Parsed rule documents are shared between calls when no -Overrides are supplied. A full run # loads 78 rule files for 46 assessments but only 43 of them are distinct (waf.security, # waf.cost, caf.management ... are each reused by up to five assessments), and ConvertFrom-Yaml # is a pure-PowerShell walk of the YAML tree at ~85 ms per file -- about half of this # function's time. The key is path + size + write time, so an edited or replaced file is # re-read. Rules are read-only to every consumer, and -Overrides patches rule objects IN PLACE, # so a call that carries overrides neither reads nor populates the cache. $useCache = -not ($Overrides -and $Overrides.Count -gt 0) if (-not (Get-Variable -Scope Script -Name ScoutRuleDocumentCache -ErrorAction Ignore)) { $script:ScoutRuleDocumentCache = @{} } $sets = foreach ($file in $files) { # ConvertFrom-Yaml returns a plain Hashtable (not a PSCustomObject) -- dotting into # a key that isn't present (e.g. a hand-edited/custom rule file missing `rules`/ # `area`/`framework`/`weight`, or an empty file, which parses to $null outright) # throws PropertyNotFoundException under Set-StrictMode -Version Latest rather # than returning $null, so every top-level key is read via ContainsKey below. $cacheKey = '{0}|{1}|{2}' -f $file.FullName, $file.Length, $file.LastWriteTimeUtc.Ticks if ($useCache -and $script:ScoutRuleDocumentCache.ContainsKey($cacheKey)) { $doc = $script:ScoutRuleDocumentCache[$cacheKey] } else { $doc = ConvertFrom-Yaml (Get-Content $file.FullName -Raw) if ($useCache -and $null -ne $doc) { $script:ScoutRuleDocumentCache[$cacheKey] = $doc } } if ($null -eq $doc) { Write-Warning "Get-RuleSet: '$($file.Name)' parsed to an empty/null YAML document -- skipping this rule file." continue } $rules = if ($doc.ContainsKey('rules')) { $doc.rules } else { @() } # AB#6817 -- a scored framework with no named version is exactly how "CIS compliance: # 72%" ends up meaningless across a 31-policy initiative and a 168-policy one, or how a # CAF page rewrite silently invalidates a coverage figure nobody re-dated. Refuse to load # a rule file that scores anything without a `frameworkversion` naming the version/date # it was measured against (see docs/frameworks/README.md). This is a load-time, # fail-fast check -- distinct from AB#6832's Unknown-at-score-time handling for data that # is simply absent at run time. if (@($rules).Count -gt 0) { $hasVersion = $doc.ContainsKey('frameworkversion') -and -not [string]::IsNullOrWhiteSpace([string]$doc.frameworkversion) if (-not $hasVersion) { throw "Get-RuleSet: '$($file.Name)' declares $(@($rules).Count) rule(s) but no 'frameworkversion' -- every scored framework must name the version/date it was measured against. Add a 'frameworkversion' key (see docs/frameworks/README.md)." } } if ($Overrides -and $Overrides.Count -gt 0) { foreach ($rule in $rules) { if (-not $rule.ContainsKey('id')) { continue } if (-not $Overrides.ContainsKey($rule.id)) { continue } if ($rule.ContainsKey('manual') -and $rule.manual) { continue } # manual rules have no numeric threshold to override if (-not $rule.ContainsKey('assert') -or $null -eq $rule.assert) { continue } $ov = $Overrides[$rule.id] $ovMap = $null if ($ov -is [hashtable]) { $ovMap = $ov } elseif ($ov -is [System.Management.Automation.PSCustomObject]) { $ovMap = @{} foreach ($p in $ov.PSObject.Properties) { $ovMap[$p.Name] = $p.Value } } if ($ovMap) { if ($ovMap.ContainsKey('value')) { $rule.assert.value = $ovMap.value } if ($ovMap.ContainsKey('type')) { $rule.assert.type = $ovMap.type } } else { $rule.assert.value = $ov } } } [pscustomobject]@{ Area = if ($doc.ContainsKey('area')) { $doc.area } else { $null } Framework = if ($doc.ContainsKey('framework')) { $doc.framework } else { $null } FrameworkVersion = if ($doc.ContainsKey('frameworkversion')) { $doc.frameworkversion } else { $null } Weight = [double]($(if ($doc.ContainsKey('weight')) { $doc.weight } else { $null }) ?? 1.0) # Optional per-file data prerequisite (AB#6832). When declared and none of the paths # resolve to rows, Invoke-Assessment reports the whole set Unknown instead of scoring # it. Without this a rule set whose inputs were never collected reads as a clean Pass: # "0 migrate projects with public access" and "no migrate project exists" are the same # count and opposite findings. Requires = @(if ($doc.ContainsKey('requires') -and $doc.requires) { $doc.requires } else { @() }) Rules = $rules } } return $sets } |