diff --git a/.codecov.yml b/.codecov.yml new file mode 100644 index 0000000..29a05dd --- /dev/null +++ b/.codecov.yml @@ -0,0 +1,24 @@ +codecov: + notify: + require_ci_to_pass: no + +comment: + layout: "reach, diff" + behavior: default + +coverage: + range: 50..80 + round: down + precision: 0 + + status: + project: + default: + # Set the overall project code coverage requirement to 70% + target: 70 + patch: + default: + # Set the pull request requirement to not regress overall coverage by more than 5% + # and let codecov.io set the goal for the code changed in the patch. + target: auto + threshold: 5 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c333d23 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +DSCResource.Tests +.vs +.vscode +node_modules diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..87b7da5 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,10 @@ +{ + "default": true, + "MD029": { + "style": "one" + }, + "MD013": true, + "MD024": false, + "MD034": false, + "no-hard-tabs": true +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..87c4308 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,13 @@ +{ + "powershell.codeFormatting.openBraceOnSameLine": false, + "powershell.codeFormatting.newLineAfterOpenBrace": false, + "powershell.codeFormatting.newLineAfterCloseBrace": true, + "powershell.codeFormatting.whitespaceBeforeOpenBrace": true, + "powershell.codeFormatting.whitespaceBeforeOpenParen": true, + "powershell.codeFormatting.whitespaceAroundOperator": true, + "powershell.codeFormatting.whitespaceAfterSeparator": true, + "powershell.codeFormatting.ignoreOneLineBlock": false, + "powershell.codeFormatting.preset": "Custom", + "files.trimTrailingWhitespace": true, + "files.insertFinalNewline": true +} diff --git a/README.md b/README.md index 61ba94a..d413ba2 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ -[![Build status](https://ci.appveyor.com/api/projects/status/wi5i60tojfd7056b/branch/master?svg=true)](https://ci.appveyor.com/project/PowerShell/xbitlocker/branch/master) - # xBitlocker + The **xBitlocker** module is a part of the Windows PowerShell Desired State Configuration (DSC) Resource Kit, which is a collection of DSC Resources produced by the PowerShell Team. This module contains the **xBLAutoBitlocker, xBLBitlocker, xBLTpm** resources. This DSC Module allows you to configure Bitlocker on a single disk, configure a TPM chip, or automatically enable Bitlocker on multiple disks. @@ -8,6 +7,26 @@ This DSC Module allows you to configure Bitlocker on a single disk, configure a This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. +## Branches + +### master + +[![Build status](https://ci.appveyor.com/api/projects/status/wi5i60tojfd7056b/branch/master?svg=true)](https://ci.appveyor.com/project/PowerShell/xBitlocker/branch/master) +[![codecov](https://codecov.io/gh/PowerShell/xBitlocker/branch/master/graph/badge.svg)](https://codecov.io/gh/PowerShell/xBitlocker/branch/master) + +This is the branch containing the latest release - +no contributions should be made directly to this branch. + +### dev + +[![Build status](https://ci.appveyor.com/api/projects/status/wi5i60tojfd7056b/branch/dev?svg=true)](https://ci.appveyor.com/project/PowerShell/xBitlocker/branch/dev) +[![codecov](https://codecov.io/gh/PowerShell/xBitlocker/branch/dev/graph/badge.svg)](https://codecov.io/gh/PowerShell/xBitlocker/branch/dev) + +This is the development branch +to which contributions should be proposed by contributors as pull requests. +This development branch will periodically be merged to the master branch, +and be released to [PowerShell Gallery](https://www.powershellgallery.com/). + ## Contributing Please check out common DSC Resources [contributing guidelines](https://github.com/PowerShell/DscResource.Kit/blob/master/CONTRIBUTING.md). @@ -17,9 +36,9 @@ To install **xBitlocker** module * Unzip the content under $env:ProgramFiles\WindowsPowerShell\Modules folder -To confirm installation: +To confirm installation: -* Run **Get-DSCResource** to see that **xBLAutoBitlocker, xBLBitlocker, xBLTpm** are among the DSC Resources listed +* Run **Get-DSCResource** to see that **xBLAutoBitlocker, xBLBitlocker, xBLTpm** are among the DSC Resources listed ## Requirements @@ -40,68 +59,78 @@ It does not work on Operating System drives. **xBLAutoBitlocker** has the following properties. Where no description is listed, properties correspond directly to [Enable-Bitlocker](http://technet.microsoft.com/en-us/library/jj649837.aspx) parameters. -* *DriveType:The type of volume, as reported by Get-Volume, to auto apply Bitlocker to +* *DriveType:The type of volume, as reported by Get-Volume, to auto apply Bitlocker to * *PrimaryProtector:The primary protector type to be used for AutoBitlocker. -Valid values are: "AdAccountOrGroupProtector", "PasswordProtector", "Pin", "RecoveryKeyProtector", "RecoveryPasswordProtector", "StartupKeyProtector", or "TpmProtector" -* MinDiskCapacityGB:If specified, only disks this size or greater will auto apply Bitlocker -* AutoUnlock:Whether volumes should be enabled for auto unlock using Enable-BitlockerAutoUnlock -* AdAccountOrGroup -* AdAccountOrGroupProtector -* EncryptionMethod -* HardwareEncryption -* Password -* PasswordProtector -* Pin -* RecoveryKeyPath -* RecoveryKeyProtector -* RecoveryPasswordProtector -* Service -* SkipHardwareTest -* StartupKeyPath -* StartupKeyProtector -* TpmProtector -* UsedSpaceOnly +Valid values are: "AdAccountOrGroupProtector", "PasswordProtector", "Pin", "RecoveryKeyProtector", "RecoveryPasswordProtector", "StartupKeyProtector", or "TpmProtector" +* MinDiskCapacityGB:If specified, only disks this size or greater will auto apply Bitlocker +* AutoUnlock:Whether volumes should be enabled for auto unlock using Enable-BitlockerAutoUnlock +* AdAccountOrGroup +* AdAccountOrGroupProtector +* EncryptionMethod +* HardwareEncryption +* Password +* PasswordProtector +* Pin +* RecoveryKeyPath +* RecoveryKeyProtector +* RecoveryPasswordProtector +* Service +* SkipHardwareTest +* StartupKeyPath +* StartupKeyProtector +* TpmProtector +* UsedSpaceOnly **xBLBitlocker** has the following properties. Where no description is listed, properties correspond directly to [Enable-Bitlocker](http://technet.microsoft.com/en-us/library/jj649837.aspx) parameters. -* *MountPoint:The MountPoint name as reported in Get-BitLockerVolume +* *MountPoint:The MountPoint name as reported in Get-BitLockerVolume * *PrimaryProtector:The primary protector type to be used for AutoBitlocker. -Valid values are: "AdAccountOrGroupProtector", "PasswordProtector", "Pin", "RecoveryKeyProtector", "RecoveryPasswordProtector", "StartupKeyProtector", or "TpmProtector" -* AutoUnlock:Whether volumes should be enabled for auto unlock using Enable-BitlockerAutoUnlock +Valid values are: "AdAccountOrGroupProtector", "PasswordProtector", "Pin", "RecoveryKeyProtector", "RecoveryPasswordProtector", "StartupKeyProtector", or "TpmProtector" +* AutoUnlock:Whether volumes should be enabled for auto unlock using Enable-BitlockerAutoUnlock * AllowImmediateReboot:Whether the computer can be immediately rebooted after enabling Bitlocker on an OS drive. Defaults to false. -* AdAccountOrGroup -* AdAccountOrGroupProtector -* EncryptionMethod -* HardwareEncryption -* Password -* PasswordProtector -* Pin -* RecoveryKeyPath -* RecoveryKeyProtector -* RecoveryPasswordProtector -* Service -* SkipHardwareTest -* StartupKeyPath -* StartupKeyProtector -* TpmProtector -* UsedSpaceOnly +* AdAccountOrGroup +* AdAccountOrGroupProtector +* EncryptionMethod +* HardwareEncryption +* Password +* PasswordProtector +* Pin +* RecoveryKeyPath +* RecoveryKeyProtector +* RecoveryPasswordProtector +* Service +* SkipHardwareTest +* StartupKeyPath +* StartupKeyProtector +* TpmProtector +* UsedSpaceOnly **xBLTpm** is used to initialize a TPM chip using [Initialize-TPM](http://technet.microsoft.com/en-us/library/jj603112.aspx). **xBLTpm** has the following properties. -* *Identity:Not actually used, so could be anything -* AllowClear:Indicates that the provisioning process clears the TPM, if necessary, to move the TPM closer to complying with Windows Server® 2012 standards +* *Identity:Not actually used, so could be anything +* AllowClear:Indicates that the provisioning process clears the TPM, if necessary, to move the TPM closer to complying with Windows Server® 2012 standards * AllowPhysicalPresence:Indicates that the provisioning process may send physical presence commands that require a user to be present in order to continue. -* AllowImmediateReboot:Whether the computer can rebooted immediately after initializing the TPM +* AllowImmediateReboot:Whether the computer can rebooted immediately after initializing the TPM ## Versions ### Unreleased + * Converted appveyor.yml to install Pester from PSGallery instead of from Chocolatey. +* Added Codecov support. +* Updated appveyor.yml to use the one in template. +* Added folders for future unit and integration tests. +* Added Visual Studio Code formatting settings. +* Added .gitignore file. +* Added markdown lint rules. +* Fixed encoding on README.md. +* Added `PowerShellVersion = '4.0'`, and updated copyright information, in the + module manifest. ### 1.1.0.0 @@ -116,10 +145,10 @@ Defaults to false. ### 1.0.0.0 -* Initial release with the following resources - * xBLAutoBitlocker - * xBLBitlocker - * xBLTpm +* Initial release with the following resources + * xBLAutoBitlocker + * xBLBitlocker + * xBLTpm ## Examples @@ -132,4 +161,4 @@ The example code for ConfigureBitlockerOnOSDrive is located in [`ConfigureBitloc Enables Bitlocker on an Operating System drive, and automatically enables Bitlocker on all drives of type 'Fixed'. The example code for ConfigureBitlockerAndAutoBitlocker is located in [`ConfigureBitlockerAndAutoBitlocker.ps1`](Examples/ConfigureBitlockerAndAutoBitlocker/ConfigureBitlockerAndAutoBitlocker.ps1). - + diff --git a/Tests/Integration/integration_template.config.ps1 b/Tests/Integration/integration_template.config.ps1 new file mode 100644 index 0000000..bb36208 --- /dev/null +++ b/Tests/Integration/integration_template.config.ps1 @@ -0,0 +1,26 @@ +<# +.Synopsis + DSC Configuration Template for DSC Resource Integration tests. +.DESCRIPTION + To Use: + 1. Copy to \Tests\Integration\ folder and rename .config.ps1 (e.g. MSFT_Firewall.config.ps1) + 2. Customize TODO sections. + +.NOTES +#> + +# Integration Test Config Template Version: 1.0.1 + +# TODO: Modify ResourceName (e.g. MSFT_Firewall_config) +configuration _config { + # TODO: Modify ModuleName (e.g. NetworkingDsc) + Import-DscResource -ModuleName '' + node localhost { + # TODO: Modify ResourceFriendlyName (e.g. Firewall_Integration_Test) + Integration_Test { + # TODO: Fill Configuration Code Here + } + } +} + +# TODO: (Optional): Add More Configuration Templates diff --git a/Tests/Integration/integration_template.ps1 b/Tests/Integration/integration_template.ps1 new file mode 100644 index 0000000..346818a --- /dev/null +++ b/Tests/Integration/integration_template.ps1 @@ -0,0 +1,87 @@ +<# +.Synopsis + Template for creating DSC Resource Integration Tests +.DESCRIPTION + To Use: + 1. Copy to \Tests\Integration\ folder and rename .Integration.tests.ps1 (e.g. MSFT_Firewall.Integration.tests.ps1) + 2. Customize TODO sections. + 3. Create test DSC Configuration file .config.ps1 (e.g. MSFT_Firewall.config.ps1) from integration_config_template.ps1 file. + +.NOTES + Code in HEADER, FOOTER and DEFAULT TEST regions are standard and may be moved into + DSCResource.Tools in Future and therefore should not be altered if possible. +#> + +# TODO: Customize these parameters... +$script:DSCModuleName = '' # Example NetworkingDsc +$script:DSCResourceName = '' # Example MSFT_Firewall + +#region HEADER +# Integration Test Template Version: 1.2.1 +[String] $script:moduleRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot) +if ( (-not (Test-Path -Path (Join-Path -Path $script:moduleRoot -ChildPath 'DSCResource.Tests'))) -or ` + (-not (Test-Path -Path (Join-Path -Path $script:moduleRoot -ChildPath 'DSCResource.Tests\TestHelper.psm1'))) ) +{ + & git @('clone', 'https://github.com/PowerShell/DscResource.Tests.git', (Join-Path -Path $script:moduleRoot -ChildPath 'DSCResource.Tests')) +} + +Import-Module -Name (Join-Path -Path $script:moduleRoot -ChildPath (Join-Path -Path 'DSCResource.Tests' -ChildPath 'TestHelper.psm1')) -Force +$TestEnvironment = Initialize-TestEnvironment ` + -DSCModuleName $script:DSCModuleName ` + -DSCResourceName $script:DSCResourceName ` + -TestType Integration + +#endregion + +# TODO: Other Init Code Goes Here... + +# Using try/finally to always cleanup. +try +{ + #region Integration Tests + $configFile = Join-Path -Path $PSScriptRoot -ChildPath "$($script:DSCResourceName).config.ps1" + . $configFile + + Describe "$($script:DSCResourceName)_Integration" { + #region DEFAULT TESTS + It 'Should compile and apply the MOF without throwing' { + { + & "$($script:DSCResourceName)_Config" -OutputPath $TestDrive + + $startDscConfigurationParameters = @{ + Path = $TestDrive + ComputerName = 'localhost' + Wait = $true + Verbose = $true + Force = $true + ErrorAction = 'Stop' + } + + Start-DscConfiguration @startDscConfigurationParameters + } | Should -Not -Throw + } + + It 'Should be able to call Get-DscConfiguration without throwing' { + { + Get-DscConfiguration -Verbose -ErrorAction Stop + } | Should -Not -Throw + } + #endregion + + It 'Should have set the resource and all the parameters should match' { + # TODO: Validate the Config was Set Correctly Here... + } + } + #endregion + +} +finally +{ + #region FOOTER + + Restore-TestEnvironment -TestEnvironment $TestEnvironment + + #endregion + + # TODO: Other Optional Cleanup Code Goes Here... +} diff --git a/Tests/Unit/unit_template.ps1 b/Tests/Unit/unit_template.ps1 new file mode 100644 index 0000000..368a2e3 --- /dev/null +++ b/Tests/Unit/unit_template.ps1 @@ -0,0 +1,110 @@ +<# + .SYNOPSIS + Template for creating DSC Resource Unit Tests + .DESCRIPTION + To Use: + 1. Copy to \Tests\Unit\ folder and rename .tests.ps1 (e.g. MSFT_xFirewall.tests.ps1) + 2. Customize TODO sections. + 3. Delete all template comments (TODOs, etc.) + + .NOTES + There are multiple methods for writing unit tests. This template provides a few examples + which you are welcome to follow but depending on your resource, you may want to + design it differently. Read through our TestsGuidelines.md file for an intro on how to + write unit tests for DSC resources: https://github.com/PowerShell/DscResources/blob/master/TestsGuidelines.md +#> + +#region HEADER + +# Unit Test Template Version: 1.2.1 +$script:moduleRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot) +if ( (-not (Test-Path -Path (Join-Path -Path $script:moduleRoot -ChildPath 'DSCResource.Tests'))) -or ` + (-not (Test-Path -Path (Join-Path -Path $script:moduleRoot -ChildPath 'DSCResource.Tests\TestHelper.psm1'))) ) +{ + & git @('clone','https://github.com/PowerShell/DscResource.Tests.git',(Join-Path -Path $script:moduleRoot -ChildPath 'DSCResource.Tests')) +} + +Import-Module -Name (Join-Path -Path $script:moduleRoot -ChildPath (Join-Path -Path 'DSCResource.Tests' -ChildPath 'TestHelper.psm1')) -Force + +# TODO: Insert the correct and for your resource +$TestEnvironment = Initialize-TestEnvironment ` + -DSCModuleName '' ` + -DSCResourceName '' ` + -TestType Unit + +#endregion HEADER + +function Invoke-TestSetup { + # TODO: Optional init code goes here... +} + +function Invoke-TestCleanup { + Restore-TestEnvironment -TestEnvironment $TestEnvironment + + # TODO: Other Optional Cleanup Code Goes Here... +} + +# Begin Testing +try +{ + Invoke-TestSetup + + InModuleScope '' { + # TODO: Optionally create any variables here for use by your tests + + # TODO: Complete the Describe blocks below and add more as needed. + # The most common method for unit testing is to test by function. For more information + # check out this introduction to writing unit tests in Pester: + # https://www.simple-talk.com/sysadmin/powershell/practical-powershell-unit-testing-getting-started/#eleventh + # You may also follow one of the patterns provided in the TestsGuidelines.md file: + # https://github.com/PowerShell/DscResources/blob/master/TestsGuidelines.md + + Describe '' { + BeforeEach { + # per-test-initialization + } + + AfterEach { + # per-test-cleanup + } + + Context 'Context-description' { + BeforeEach { + # per-test-initialization + } + + AfterEach { + # per-test-cleanup + } + + It 'Should...test-description' { + # test-code + } + + It 'Should...test-description' { + # test-code + } + } + + Context 'Context-description' { + It 'Should ....test-description' { + # test-code + } + } + } + + Describe '' { + Context '' { + It 'Should ...test-description' { + # test-code + } + } + } + + # TODO: add more Describe blocks as needed + } +} +finally +{ + Invoke-TestCleanup +} diff --git a/appveyor.yml b/appveyor.yml index 22fe6aa..1f648e1 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -1,63 +1,33 @@ -#---------------------------------# -# environment configuration # -#---------------------------------# +#---------------------------------# +# environment configuration # +#---------------------------------# + version: 1.1.{build}.0 install: - git clone https://github.com/PowerShell/DscResource.Tests - - ps: | - Import-Module -Name .\DscResource.Tests\TestHelper.psm1 -Force - Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force - Install-Module -Name Pester -Repository PSGallery -Force + - ps: Write-Verbose -Message "PowerShell version $($PSVersionTable.PSVersion)" -Verbose + - ps: Import-Module "$env:APPVEYOR_BUILD_FOLDER\DscResource.Tests\AppVeyor.psm1" + - ps: Invoke-AppveyorInstallTask -#---------------------------------# -# build configuration # -#---------------------------------# +#---------------------------------# +# build configuration # +#---------------------------------# build: false -#---------------------------------# -# test configuration # -#---------------------------------# +#---------------------------------# +# test configuration # +#---------------------------------# test_script: - ps: | - $testResultsFile = ".\TestsResults.xml" - $res = Invoke-Pester -OutputFormat NUnitXml -OutputFile $testResultsFile -PassThru - (New-Object 'System.Net.WebClient').UploadFile("https://ci.appveyor.com/api/testresults/nunit/$($env:APPVEYOR_JOB_ID)", (Resolve-Path $testResultsFile)) - if ($res.FailedCount -gt 0) { - throw "$($res.FailedCount) tests failed." - } - -#---------------------------------# -# deployment configuration # -#---------------------------------# - -# scripts to run before deployment -deploy_script: - - ps: | - # Creating project artifact - $stagingDirectory = (Resolve-Path ..).Path - $manifest = Join-Path $pwd "xBitlocker.psd1" - (Get-Content $manifest -Raw).Replace("1.1.0.0", $env:APPVEYOR_BUILD_VERSION) | Out-File $manifest - $zipFilePath = Join-Path $stagingDirectory "$(Split-Path $pwd -Leaf).zip" - Add-Type -assemblyname System.IO.Compression.FileSystem - [System.IO.Compression.ZipFile]::CreateFromDirectory($pwd, $zipFilePath) - - # Creating NuGet package artifact - New-Nuspec -packageName $env:APPVEYOR_PROJECT_NAME -version $env:APPVEYOR_BUILD_VERSION -author "Microsoft" -owners "Microsoft" -licenseUrl "https://github.com/PowerShell/DscResources/blob/master/LICENSE" -projectUrl "https://github.com/$($env:APPVEYOR_REPO_NAME)" -packageDescription $env:APPVEYOR_PROJECT_NAME -tags "DesiredStateConfiguration DSC DSCResourceKit" -destinationPath . - nuget pack ".\$($env:APPVEYOR_PROJECT_NAME).nuspec" -outputdirectory . - $nuGetPackageName = $env:APPVEYOR_PROJECT_NAME + "." + $env:APPVEYOR_BUILD_VERSION + ".nupkg" - $nuGetPackagePath = (Get-ChildItem $nuGetPackageName).FullName - - @( - # You can add other artifacts here - $zipFilePath, - $nuGetPackagePath - ) | % { - Write-Host "Pushing package $_ as Appveyor artifact" - Push-AppveyorArtifact $_ - } - - + Invoke-AppveyorTestScriptTask -CodeCoverage -CodeCovIo -ExcludeTag @() +#---------------------------------# +# deployment configuration # +#---------------------------------# +# scripts to run before deployment +deploy_script: + - ps: | + Invoke-AppveyorAfterTestTask diff --git a/xBitlocker.psd1 b/xBitlocker.psd1 index 50e5cbc..a2aeb8f 100644 --- a/xBitlocker.psd1 +++ b/xBitlocker.psd1 @@ -1,10 +1,4 @@ -# -# Module manifest for module 'xBitlocker' -# -# Generated by: Mike Hendrickson -# -# Generated on: 8/29/2014 -# + @{ @@ -18,19 +12,19 @@ ModuleVersion = '1.1.0.0' GUID = 'dc4f3fd0-4e1d-4916-84f8-d0bb89d52507' # Author of this module -Author = 'Mike Hendrickson' +Author = 'Microsoft Corporation' # Company or vendor of this module -CompanyName = 'Microsoft' +CompanyName = 'Microsoft Corporation' # Copyright statement for this module -Copyright = '(c) 2014 administrator. All rights reserved.' +Copyright = '(c) 2018 Microsoft Corporation. All rights reserved.' # Description of the functionality provided by this module Description = 'This DSC Module allows you to configure Bitlocker on a single disk, configure a TPM chip, or automatically enable Bitlocker on multiple disks.' # Minimum version of the Windows PowerShell engine required by this module -# PowerShellVersion = '' +PowerShellVersion = '4.0' # Name of the Windows PowerShell host required by this module # PowerShellHostName = ''