Introducing DSCEA

***This post was written by Ralph Kyttle, PFE, and back linked to the original post. The original post can be found at: https://blogs.technet.microsoft.com/ralphkyttle/2017/03/21/introducing-dscea/

Hello, World!

I am incredibly excited to announce the open source release of DSC Environment Analyzer (DSCEA), a PowerShell module that uses the declarative nature of Desired State Configuration to scan systems in an environment against a defined reference MOF file and generate compliance reports as to whether systems match the desired configuration.

DSCEA includes a customizable reporting engine that can provide reports on overall compliance and details on any DSC resource found to be non-compliant.  DSCEA utilizes the DSC processing engine and DSC resources to audit and report on the existing configuration of machines in an environment.

By using PowerShell Desired State Configuration at its core, DSCEA obtains some unique advantages. Most notably, by defining the desired configuration state using DSC, an admin can benefit from using the same work to both scan for compliance and then correct items that were found to be non-compliant. Building an audit file in DSC can help ease remediations, and in some cases it can be as simple as applying the same MOF file that was used to scan an environment onto systems to correct drift and bring things into the desired state.

DSCEA is hosted at https://github.com/Microsoft/DSCEA and can be downloaded from the PowerShell Gallery.

DSCEA documentation is hosted at https://microsoft.github.io/DSCEA

So, now that DSCEA is available, what does that mean for you?

DSCEA’s primary use case is to verify that your systems are actually configured the way you want them to be.

Real world examples of how DSCEA can be used include

• Verifying a single setting, for example if a registry key is set appropriately across your entire environment

• Auditing your systems to ensure that they meet the base level system configuration settings that are required to be a part of your environment
• Scanning the systems in your environment against all of the items that make up your organization’s security baseline
• Verifying that settings configured via Group Policy are being applied correctly to the systems in your environment
• Verifying settings configured on Windows Server 2016 Nano servers (which do not support Group Policy)
• Let’s take a look at the first example, to see how DSCEA can be used to verify that certain registry keys are set correctly on a group of systems in an environment.

  First, you will need to install the DSCEA PowerShell module onto the computer that will act as your management system from where you will execute the scan from.  Click here for instructions on installing the DSCEA module.

  Next, you need to create a DSC configuration that defines the desired state you would like to scan for.  Here is an example that defines a desired state for the security related crashonaudit registry key.

  configuration DSCEARegistryTest1 {
      param([string[]]$ComputerName='localhost')
  
      Import-DscResource -ModuleName PSDesiredStateConfiguration
  
      Node $ComputerName {
  
          Registry 'CrashOnAuditFail' {
              Ensure    = 'Present'
              Key       = 'HKEY_LOCAL_MACHINESYSTEMCurrentControlSetControlLsa'
              ValueName = 'crashonauditfail'
              ValueType = 'Dword'
              ValueData = '1'
          }
  
      }
  }
  
  DSCEARegistryTest1 -OutputPath .

  view raw DSCEARegistryTest1.ps1 hosted with by GitHub

  Run the DSCEARegistryTest1.ps1 file, which creates an output file called localhost.mof in your current directory which you will then use to scan systems in your environment.

  Click here for examples on how to execute a DSCEA scan.  One example is included below.

  Scan multiple systems for compliance to settings defined within a localhost.mof file located in your current directory

  PS C:> Start-DSCEAscan -MofFile .localhost.mof -ComputerName dsctest-1, dsctest-2, dsctest-3

  This command executes a DSCEA scan against 3 remote systems, dsctest-1, dsctest-2 and dsctest-3 using a locally defined MOF file that exists in the current directory. This MOF file specifies the settings to check for during the scan. Start-DSCEAscan returns a XML results file containing raw data that can be used with other functions, such as Get-DSCEAreport to create reports with consumable information.

  Generate HTML Reports based on scan results – System Compliance

  Once you have completed a scan, you will want to generate reports.  Click here for instructions on creating HTML based reports with DSCEA.  Two examples are included below.

  PS C:UsersusernameDocumentsDSCEA> Get-DSCEAreport -Overall

  This command is executed from a directory that contains DSCEA scan result XML files. It generates a report of overall system compliance, and will mark a system as non-compliant if it does not fully match the desired configuration.

  Example HTML Report #1

  
  Next we will use Get-DSCEAreport to generate a report showing all non-compliant items that were detected.

  PS C:UsersusernameDocumentsDSCEA> Get-DSCEAreport -Detailed

  This command is executed from a directory that contains DSCEA scan result XML files. It generates a report containing a list of all items that were found to be non-compliant. If all systems that are scanned are found to be compliant, this report will show no results.

  Example HTML Report #2

  Feeling creative?  DSCEA XML data can be converted into CSV, for use with other tools like PowerBI

  This post is just the first of many, as we will continue to explore the ways you can use DSCEA in your environment to verify that your systems are actually configured the way you want them to be.

  DSCEA is an open source solution hosted on GitHub.  We look forward to your feedback and contributions!