Sync main with develop

.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: UTC
+    target-branch: develop
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: build
+      include: scope

.github/workflows/dependency-review.yml

@@ -0,0 +1,27 @@
+# Dependency Review Action
+#
+# This Action will scan dependency manifest files that change as part of a Pull Request,
+# surfacing known-vulnerable versions of the packages declared or updated in the PR.
+# Once installed, if the workflow run is marked as required,
+# PRs introducing known-vulnerable packages will be blocked from merging.
+#
+# Source repository: https://github.com/actions/dependency-review-action
+name: 'Dependency Review'
+on: [pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          egress-policy: audit
+
+      - name: 'Checkout Repository'
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: 'Dependency Review'
+        uses: actions/dependency-review-action@3c4e3dcb1aa7874d2c16be7d79418e9b7efd6261 # v4.8.2

.github/workflows/pester.yml

@@ -0,0 +1,139 @@
+name: Pester
+
+on:
+  pull_request:
+    paths:
+      - "**/*.ps1"
+      - "**/*.psm1"
+      - "**/*.psd1"
+      - "Tests/**"
+      - ".github/workflows/pester.yml"
+  push:
+    branches:
+      - develop
+      - main
+    paths:
+      - "**/*.ps1"
+      - "**/*.psm1"
+      - "**/*.psd1"
+      - "Tests/**"
+      - ".github/workflows/pester.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  PESTER_VERSION: '5.7.1'
+
+jobs:
+  test:
+    name: Run Pester tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Harden runner
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          egress-policy: block
+          allowed-endpoints: >
+            github.com:443
+            *.github.com:443
+            *.githubusercontent.com:443
+            www.powershellgallery.com:443
+
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Validate pinned Pester version
+        shell: pwsh
+        run: |
+          Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
+          $null = Find-Module -Name 'Pester' -RequiredVersion '${{ env.PESTER_VERSION }}' -Repository PSGallery -ErrorAction Stop
+          Write-Host "Using pinned Pester version ${{ env.PESTER_VERSION }}"
+
+      - name: Cache Pester module
+        uses: actions/cache@9255dc7a253b0ccc959486e2bca901246202afeb # v5.0.1
+        with:
+          path: ~/.local/share/powershell/Modules/Pester
+          key: pester-${{ runner.os }}-${{ env.PESTER_VERSION }}
+          restore-keys: |
+            pester-${{ runner.os }}-
+
+      - name: Install Pester
+        shell: pwsh
+        run: |
+          $moduleName = 'Pester'
+          $requiredVersion = [Version]$env:PESTER_VERSION
+
+          $installed = Get-Module -ListAvailable -Name $moduleName | Where-Object { $_.Version -eq $requiredVersion }
+          if (-not $installed) {
+              Install-Module -Name $moduleName -RequiredVersion $requiredVersion.ToString() -Scope CurrentUser -Force -AllowClobber
+          }
+
+          Get-Module -ListAvailable -Name $moduleName | Where-Object { $_.Version -eq $requiredVersion } |
+              Select-Object -First 1 |
+              Format-List Name, Version, ModuleBase
+
+      - name: Run Pester tests
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Stop'
+          $resultsPath = Join-Path -Path $PWD -ChildPath 'Output/TestResults'
+          if (-not (Test-Path -Path $resultsPath)) {
+              New-Item -ItemType Directory -Path $resultsPath -Force | Out-Null
+          }
+
+          if (-not (Test-Path -Path 'Tests')) {
+              Write-Host 'No Pester tests found (Tests folder missing). Skipping.'
+              exit 0
+          }
+
+          $testFiles = Get-ChildItem -Path 'Tests' -Filter '*.ps1' -File -Recurse -ErrorAction SilentlyContinue
+          if (-not $testFiles) {
+              Write-Host 'No Pester test files found under Tests. Skipping.'
+              exit 0
+          }
+
+          $requiredVersion = [Version]$env:PESTER_VERSION
+          Import-Module -Name Pester -RequiredVersion $requiredVersion.ToString() -Force
+
+          $config = [PesterConfiguration]::Default
+          $config.Run.Path = 'Tests'
+          $config.Run.PassThru = $true
+          $config.Output.Verbosity = 'Detailed'
+          $config.TestResult.Enabled = $true
+          $config.TestResult.OutputFormat = 'JUnitXml'
+          $config.TestResult.OutputPath = Join-Path -Path $resultsPath -ChildPath 'PesterResults.xml'
+          $coverageTargets = @(
+              'DomainSecurityAuditor.psm1'
+              'Public'
+              'Private'
+              'Examples'
+          ) | Where-Object { Test-Path -Path $_ }
+          if ($coverageTargets) {
+              $config.CodeCoverage.Enabled = $true
+              $config.CodeCoverage.OutputFormat = 'JaCoCo'
+              $config.CodeCoverage.OutputPath = Join-Path -Path $resultsPath -ChildPath 'PesterCoverage.xml'
+              $config.CodeCoverage.Path = $coverageTargets
+          }
+          else {
+              $config.CodeCoverage.Enabled = $false
+              Write-Host 'No coverage targets found; skipping code coverage.'
+          }
+
+          $result = Invoke-Pester -Configuration $config
+          $result | Format-List -Property *
+
+          if ($result.FailedCount -gt 0) {
+              throw "Pester reported $($result.FailedCount) failed tests."
+          }
+
+      - name: Upload Pester results
+        if: always()
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: pester-results
+          path: Output/TestResults/*.xml
+          retention-days: 14
+          if-no-files-found: warn

.github/workflows/psscriptanalyzer.yml

@@ -0,0 +1,105 @@
+name: PSScriptAnalyzer
+
+on:
+  pull_request:
+    paths:
+      - "**/*.ps1"
+      - "**/*.psm1"
+      - "**/*.psd1"
+      - "PSScriptAnalyzerSettings.psd1"
+      - ".github/workflows/psscriptanalyzer.yml"
+  push:
+    branches:
+      - develop
+      - main
+    paths:
+      - "**/*.ps1"
+      - "**/*.psm1"
+      - "**/*.psd1"
+      - "PSScriptAnalyzerSettings.psd1"
+      - ".github/workflows/psscriptanalyzer.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: Run PSScriptAnalyzer
+    runs-on: ubuntu-latest
+    env:
+      PSSA_VERSION: "1.24.0"
+
+    steps:
+      - name: Harden runner
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          egress-policy: block
+          allowed-endpoints: >
+            github.com:443
+            *.github.com:443
+            *.githubusercontent.com:443
+            www.powershellgallery.com:443
+
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Cache PowerShell modules
+        uses: actions/cache@9255dc7a253b0ccc959486e2bca901246202afeb # v5.0.1
+        with:
+          path: ~/.local/share/powershell/Modules/PSScriptAnalyzer
+          key: pssa-${{ runner.os }}-${{ env.PSSA_VERSION }}-${{ hashFiles('PSScriptAnalyzerSettings.psd1') }}
+          restore-keys: |
+            pssa-${{ runner.os }}-
+
+      - name: Install PSScriptAnalyzer
+        shell: pwsh
+        run: |
+          $moduleName = 'PSScriptAnalyzer'
+          $requiredVersion = [Version]'${{ env.PSSA_VERSION }}'
+
+          $installed = Get-Module -ListAvailable -Name $moduleName | Where-Object { $_.Version -eq $requiredVersion }
+          if (-not $installed) {
+              Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
+              Install-Module -Name $moduleName -RequiredVersion $requiredVersion.ToString() -Scope CurrentUser -Force -AllowClobber
+          }
+
+          Get-Module -ListAvailable -Name $moduleName | Where-Object { $_.Version -eq $requiredVersion } |
+              Select-Object -First 1 |
+              Format-List Name, Version, ModuleBase
+
+      - name: Analyze PowerShell scripts
+        shell: pwsh
+        run: |
+          $settingsPath = Join-Path $PWD 'PSScriptAnalyzerSettings.psd1'
+          if (-not (Test-Path $settingsPath)) {
+              Write-Error "Settings file not found at $settingsPath"
+              exit 1
+          }
+
+          $paths = @(
+              'DomainSecurityAuditor.psm1'
+              'DomainSecurityAuditor.psd1'
+              'Public'
+              'Private'
+              'Examples'
+              'Tests'
+          ) | Where-Object { Test-Path $_ }
+
+          if (-not $paths) {
+              Write-Error 'No PowerShell paths found to analyze'
+              exit 1
+          }
+
+          $ErrorActionPreference = 'Stop'
+          $results = @()
+          foreach ($p in $paths) {
+              $results += Invoke-ScriptAnalyzer -Path $p -Recurse -Settings $settingsPath
+          }
+
+          if ($results) {
+              $results | Format-Table RuleName, Severity, ScriptName, Line, Message -AutoSize
+              Write-Host "`nTotal issues: $($results.Count)"
+              exit 1
+          }
+          Write-Host 'No issues found.'

.github/workflows/scorecards.yml

@@ -0,0 +1,81 @@
+# This workflow uses actions that are not certified by GitHub. They are provided
+# by a third-party and are governed by separate terms of service, privacy
+# policy, and support documentation.
+
+name: Scorecard supply-chain security
+on:
+  # For Branch-Protection check. Only the default branch is supported. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection
+  branch_protection_rule:
+  # To guarantee Maintained check is occasionally updated. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained
+  schedule:
+    - cron: '20 7 * * 2'
+  push:
+    branches: ["develop"]
+
+# Declare default permissions as read only.
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      # Needed to upload the results to code-scanning dashboard.
+      security-events: write
+      # Needed to publish results and get a badge (see publish_results below).
+      id-token: write
+      contents: read
+      actions: read
+      # To allow GraphQL ListCommits to work
+      issues: read
+      pull-requests: read
+      # To detect SAST tools
+      checks: read
+
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          egress-policy: audit
+
+      - name: "Checkout code"
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+
+      - name: "Run analysis"
+        uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          # (Optional) "write" PAT token. Uncomment the `repo_token` line below if:
+          # - you want to enable the Branch-Protection check on a *public* repository, or
+          # - you are installing Scorecards on a *private* repository
+          # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action#authentication-with-pat.
+          # repo_token: ${{ secrets.SCORECARD_TOKEN }}
+
+          # Public repositories:
+          #   - Publish results to OpenSSF REST API for easy access by consumers
+          #   - Allows the repository to include the Scorecard badge.
+          #   - See https://github.com/ossf/scorecard-action#publishing-results.
+          # For private repositories:
+          #   - `publish_results` will always be set to `false`, regardless
+          #     of the value entered here.
+          publish_results: true
+
+      # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
+      # format to the repository Actions tab.
+      - name: "Upload artifact"
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      # Upload the results to GitHub's code scanning dashboard.
+      - name: "Upload to code-scanning"
+        uses: github/codeql-action/upload-sarif@5d4e8d1aca955e8d8589aabd499c5cae939e33c7 # v4.31.9
+        with:
+          sarif_file: results.sarif

.gitignore

@@ -23,6 +23,11 @@ Desktop.ini
 .vscode-server/
 *.code-workspace.user
 
+# ----------------------------
+# Tooling
+# ----------------------------
+.claude/
+
 # ----------------------------
 # PowerShell
 # ----------------------------
@@ -61,6 +66,7 @@ codecoverage*.xml
 # Build Artifacts
 # ----------------------------
 Output/*
+!Output/.gitkeep
 build/
 dist/
 *.nupkg
@@ -78,6 +84,8 @@ Reports/*.xml
 # ----------------------------
 *.log
 logs/*
+Logs/*
+!Logs/.gitkeep
 
 # ----------------------------
 # CI/CD (GitHub Actions)