feat: create ps module ac helpers

Created a new PowerShell module containing Windows ACL helper functions:

* Enabling ACL inheritance
* Protecting a file (removes ACL inheritance and changes file permissions)

.editorconfig

@@ -0,0 +1,21 @@
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+# Matches multiple files with brace expansion notation
+# Set default charset
+[*.{ps1,psd1,psm1,yml}]
+charset = utf-8
+
+# 4 space indentation
+[*.{ps1,psd1,psm1}]
+indent_style = space
+indent_size = 4
+
+[*.yml]
+indent_style = space
+indent_size = 2

.gitattributes

@@ -0,0 +1 @@
+*.* eol=lf

.github/workflows/github-actions-push.yml

@@ -0,0 +1,123 @@
+name: compendium.aclhelpers pipeline
+on:
+  push:
+  pull_request:
+    branches:
+    - main
+env:
+  MODULE_SOURCE: src/Compendium.AclHelpers
+  ARTIFACT_NAME: Compendium.AclHelpers
+defaults:
+  run:
+    shell: pwsh
+jobs:
+  SemanticVersion:
+    runs-on: ubuntu-latest
+    outputs:
+      semantic_version: ${{ steps.semantic_release.outputs.SEMANTIC_VERSION }}
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+      with:
+        persist-credentials: false
+    - name: Setup Node Version
+      uses: actions/setup-node@master
+      with:
+        node-version: 18
+    - name: Node Package Restore
+      run: ./build/scripts/Install-NodePackages.ps1
+    - name: Semantic Release (Dry-Run)
+      id: semantic_release
+      run: ./build/scripts/Invoke-SemanticRelease.ps1 -DryRun
+      env:
+        GH_TOKEN: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
+        GH_REF: ${{ github.ref }}
+  Build:
+    runs-on: windows-latest # MUST be run on Windows because this is a Windows specific module for manipulating Windows filesystem ACL
+    needs: SemanticVersion
+    defaults:
+      run:
+        shell: pwsh
+        working-directory: build/scripts
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+    - name: Install PowerShell Modules
+      run: |
+        . ./Packages.ps1
+        Install-PowerShellModules
+    - name: Run PSScriptAnalyzer
+      run: |
+        ./Debug-Scripts.ps1 -Path "$env:GITHUB_WORKSPACE/$env:MODULE_SOURCE"
+    - name: Run Pester Tests
+      run: |
+        ./Test-Module.ps1
+    - name: Update Module Manifest
+      run: |
+        ./Set-SemanticVersion.ps1 -PSModuleManifestFilePath "$env:GITHUB_WORKSPACE/$env:MODULE_SOURCE/Compendium.AclHelpers.psd1" -SemanticVersion "${{ needs.SemanticVersion.outputs.semantic_version }}"
+    - name: Publish Artifact
+      uses: actions/upload-artifact@v3
+      with:
+        name: ${{ env.ARTIFACT_NAME }}
+        path: ${{ env.MODULE_SOURCE }}
+  GitHubRelease:
+    if: ${{ github.ref == 'refs/heads/main' && github.event_name != 'pull_request' }}
+    runs-on: ubuntu-latest
+    needs:
+    - SemanticVersion
+    - Build
+    defaults:
+      run:
+        shell: pwsh
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+    - name: Download Artifact
+      uses: actions/download-artifact@v3
+      with:
+        name: ${{ env.ARTIFACT_NAME }}
+        path: a/${{ env.ARTIFACT_NAME }}
+    - name: Setup Node Version
+      uses: actions/setup-node@master
+      with:
+        node-version: 18
+    - name: Node Package Restore
+      run: ./build/scripts/Install-NodePackages.ps1
+    - name: Update Module Manifest
+      run: |
+        ./build/scripts/Set-SemanticVersion.ps1 -PSModuleManifestFilePath "$env:GITHUB_WORKSPACE/$env:MODULE_SOURCE/Compendium.AclHelpers.psd1" -SemanticVersion "${{ needs.SemanticVersion.outputs.semantic_version }}"
+    - name: Create Release Package
+      run: |
+        ./build/scripts/New-ReleasePackage.ps1 -ArtifactPath "$env:GITHUB_WORKSPACE/a/$env:ARTIFACT_NAME" -ReleasePackageFilePath "$env:GITHUB_WORKSPACE/b/$env:ARTIFACT_NAME.zip"
+    - name: Install Microsoft SBOM Tool
+      run: |
+        ./build/scripts/Install-MicrosoftSbomTool.ps1 -OSArch '-linux-x64' -InstallPath "$env:RUNNER_TEMP"
+    - name: Generate SBOM
+      run: |
+        ./build/scripts/New-SoftwareBillOfMaterials.ps1 -ReleasePath "$env:GITHUB_WORKSPACE/b" -SourcePath "$env:GITHUB_WORKSPACE/src" -PackageName $env:ARTIFACT_NAME -Version "${{ needs.SemanticVersion.outputs.semantic_version }}"
+    - name: Semantic Release (Dry-Run)
+      id: semantic_release
+      run: ./build/scripts/Invoke-SemanticRelease.ps1
+      env:
+        GH_TOKEN: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
+  PowerShellGalleryRelease:
+    if: ${{ github.ref == 'refs/heads/main' && github.event_name != 'pull_request' }}
+    runs-on: ubuntu-latest
+    needs:
+    - GitHubRelease
+    defaults:
+      run:
+        shell: pwsh
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+    - name: Download Artifact
+      uses: actions/download-artifact@v3
+      with:
+        name: ${{ env.ARTIFACT_NAME }}
+        path: a/${{ env.ARTIFACT_NAME }}
+    - name: Publish Module
+      run: |
+        ./build/scripts/Publish-Module.ps1 -ModulePath "$env:GITHUB_WORKSPACE/a/$env:ARTIFACT_NAME" -ReleaseNotesFilePath "$env:GITHUB_WORKSPACE/RELEASE-NOTES.md"
+      env:
+        NUGETAPIKEY: ${{ secrets.NUGETAPIKEY }}

.gitignore

@@ -0,0 +1,2 @@
+*.zip
+node_modules

.releaserc.yml

@@ -0,0 +1,28 @@
+branches:
+  - main
+
+plugins:
+  - path: "@semantic-release/commit-analyzer"
+    preset: conventionalcommits
+    releaseRules:
+    - type: docs
+      release: patch
+    - type: refactor
+      release: patch
+  - path: "@semantic-release/release-notes-generator"
+    preset: conventionalcommits
+  - path: "@semantic-release/changelog"
+  - path: "@semantic-release/exec"
+    verifyReleaseCmd: "echo '${nextRelease.version}' > SEMANTIC-VERSION.txt"
+    generateNotesCmd: "echo '${nextRelease.notes}' > RELEASE-NOTES.md"
+  - path: "@semantic-release/github"
+    assets:
+    - path: b/Compendium.AclHelpers.zip
+      label: Compendium.AclHelpers.zip
+    - path: b/_manifest/spdx_2.2/manifest.spdx.json
+      label: manifest.spdx.json
+  - path: "@semantic-release/git"
+    assets:
+    - CHANGELOG.md
+    - RELEASE-NOTES.md
+    - src/Compendium.AclHelpers/Compendium.AclHelpers.psd1

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Richard
+Copyright (c) 2022 Richard Bolhofer
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,2 +1,2 @@
-# powershell-module-aclutils
-PowerShell module with utility helpers for Windows ACL.
+# Compenidum.AclHelpers
+PowerShell module with helper functions for Windows ACL.

build/scripts/Debug-Scripts.ps1

@@ -0,0 +1,14 @@
+param (
+    [Parameter(Mandatory = $True)] [String] $Path
+)
+
+. $PSScriptRoot/Packages.ps1
+Import-PowerShellModules
+
+Invoke-Scriptanalyzer -Path $Path -Recurse -OutVariable 'Issues'
+
+$Pass = ($Issues | Where-Object { $_.Severity -eq 'Error' }).Count -eq 0
+
+if(-not($Pass)) {
+    Write-Error -Message "Script errors detected." -ErrorAction 'Stop'
+}

build/scripts/Install-MicrosoftSbomTool.ps1

@@ -0,0 +1,17 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [ValidateSet('-linux-x64', '-osx-x64', '-win-x64.exe')]
+    [string] $OSArch,
+    [string] $InstallPath
+)
+
+$LatestRelease = Invoke-RestMethod -Uri 'https://api.github.com/repos/microsoft/sbom-tool/releases/latest' -Method 'Get'
+$Url = ($LatestRelease.assets | Where-Object { $_.name -match "sbom-tool$OSArch" } | Select-Object -First 1).browser_download_url
+$InstallFilePath = (Join-Path -Path $InstallPath -ChildPath "sbom-tool$(if($OSArch -match 'win') { '.exe' } else { '' })")
+Invoke-WebRequest -Uri $Url -OutFile $InstallFilePath
+
+if(-not ($OSArch -match 'win')) {
+    chmod +x $InstallFilePath
+}
+
+Write-Output $InstallPath >> $env:GITHUB_PATH

build/scripts/Install-NodePackages.ps1

@@ -0,0 +1 @@
+npm install

build/scripts/Invoke-SemanticRelease.ps1

@@ -0,0 +1,17 @@
+param(
+    [switch] $DryRun
+)
+
+if($env:GH_REF -eq 'refs/heads/main') {
+    if($DryRun) {
+        npx semantic-release --dry-run
+    }
+    else {
+        npx semantic-release
+    }
+
+    Write-Output "SEMANTIC_VERSION=$(Get-Content -Path 'SEMANTIC-VERSION.txt')" >> $env:GITHUB_OUTPUT
+}
+else {
+    Write-Output "SEMANTIC_VERSION=0.0.1" >> $env:GITHUB_OUTPUT
+}

build/scripts/New-ReleasePackage.ps1

@@ -0,0 +1,15 @@
+param(
+    [string] $ArtifactPath,
+    [string] $ReleasePackageFilePath
+)
+
+if(Test-Path -Path $ArtifactPath) {
+    if(-not (Test-Path -Path (Split-Path -Path $ReleasePackageFilePath -Parent))) {
+        New-Item -ItemType Directory -Path (Split-Path -Path $ReleasePackageFilePath -Parent) -Force
+    }
+
+    Compress-Archive -Path $ArtifactPath -DestinationPath $ReleasePackageFilePath
+}
+else {
+    throw "$ArtifactPath not found."
+}

build/scripts/New-SoftwareBillOfMaterials.ps1

@@ -0,0 +1,10 @@
+param(
+    [string] $ReleasePath,
+    [string] $SourcePath,
+    [string] $PackageName,
+    [string] $Version,
+    [string] $Owner = "$env:GITHUB_REPOSITORY_OWNER",
+    [string] $Namespace = "$env:GITHUB_SERVER_URL/$env:GITHUB_REPOSITORY"
+)
+
+sbom-tool generate -b "$ReleasePath" -bc "$SourcePath" -pn "$PackageName" -pv "$Version" -ps "$Owner" -nsb "$Namespace"

build/scripts/Packages.ps1

@@ -0,0 +1,18 @@
+$Modules = @(
+    @{ Name = 'PSScriptAnalyzer'; Repository = 'PSGallery'; RequiredVersion = '1.21.0'; AllowClobber = $true; Force = $true }
+    @{ Name = 'Pester'; Repository = 'PSGallery'; RequiredVersion = '5.4.0'; AllowClobber = $true; Force = $true }
+)
+
+function Install-PowerShellModules {
+    foreach($Module in $Modules) {
+        Install-Module @Module
+    }
+}
+
+function Import-PowerShellModules {
+    foreach($Module in $Modules) {
+        $Module.Remove('Repository')
+        $Module.Remove('AllowClobber')
+        Import-Module @Module
+    }
+}

build/scripts/Publish-Module.ps1

@@ -0,0 +1,11 @@
+param(
+    [string] $ModulePath,
+    [string] $ReleaseNotesFilePath
+)
+
+if(Test-Path -Path $ReleaseNotesFilePath) {
+    Publish-Module -Name $ModulePath -Repository 'PSGallery' -NuGetApiKey $env:NUGETAPIKEY -ReleaseNotes (Get-Content -Path $ReleaseNotesFilePath)
+}
+else {
+    throw "$ReleaseNotesFilePath not found."
+}

build/scripts/Set-SemanticVersion.ps1

@@ -0,0 +1,11 @@
+param(
+    [Parameter(Mandatory = $True)] [String] $PSModuleManifestFilePath,
+    [Parameter(Mandatory = $True)] [string] $SemanticVersion
+)
+
+if(Test-Path -Path $PSModuleManifestFilePath) {
+    Update-ModuleManifest -Path $PSModuleManifestFilePath -ModuleVersion $SemanticVersion
+}
+else {
+    throw "$PSModuleManifestFilePath does not exist."
+}

build/scripts/Test-Module.ps1

@@ -0,0 +1,4 @@
+. $PSScriptRoot/Packages.ps1
+Import-PowerShellModules
+Set-Location -Path $env:GITHUB_WORKSPACE
+Invoke-Pester