Introducing DSCEA


Updated with a link to the latest release announcement, DSCEA 1.2.0.0
https://blogs.technet.microsoft.com/ralphkyttle/2017/04/05/dscea-1-2-0-0-has-been-released-introducing-exciting-new-updates-to-start-dsceascan/

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.

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:\Users\username\Documents\DSCEA> 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:\Users\username\Documents\DSCEA> 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!


Comments (8)

  1. ShantanuVinze says:

    Was Waiting for this POST Eagerly!! THANK YOU FOLKS.. Splendid Work.

    1. Ralph Kyttle says:

      Thank you Shantanu!

  2. Sunil Nair says:

    If anyone has been waiting for a reason to start using DSC – Well, wait no more – DSCEA is just awesome!! Been trying/testing it out this weekend and loving it!

  3. Jonathan Smith says:

    Ran into an issue with the Start-DSCEAscan function. The environment I am working in has a different AD Domain vs DNS, the script seems to auto generate the full computer object name for the WinRM call then fails with kerberos errors . Looked through the script and didn’t see an easy way to change this like I have in the past with xExchange by editing the common template.

    Is there an easy way around this beyond messing with an SPN or hostfile or something?

    1. Ralph Kyttle says:

      Hi Jonathan,

      Please take a look at the following:
      https://microsoft.github.io/DSCEA/mydoc_scan.html

      Could Example 6 work in your case? I’m thinking you should be able to get things working using the CimSession option, please let us know

Skip to main content