Walkthrough: Creating a Security Add-in Using XML and PowerShell

Article
04/13/2011

This walkthrough demonstrates how to use XML and Windows PowerShell to create an add-in that adds a security component to the list on the Security tab of the Windows SBS Console. The add-in will provide the status of the security component and detailed information about the security component. For this walkthrough, the Windows Firewall will represent the security component that will be added.

This walkthrough illustrates the following tasks:

Creating a security add-in using XML and Windows PowerShell.
Deploying the security add-in.

Prerequisites

This walkthrough assumes that you have a basic understanding of XML and Windows PowerShell. To learn more about using PowerShell, download the “Windows PowerShell 1.0 Documentation Pack” from the Microsoft Web site (https://go.microsoft.com/fwlink/?LinkId=120542). For more information about using XML, see “XML Overviews” at the Microsoft Web site (https://go.microsoft.com/fwlink/?LinkId=120543).

Note

You do not need to download Windows PowerShell because it is provided with Windows® Small Business Server 2008. It is recommended that you test your Windows PowerShell scripts before you add them to a security add-in.

Creating a Security Add-in

In this section, an .xml file is created that contains the elements and attributes that represent a security component. The security component will be added to the Security tab of the Windows SBS Console. Windows PowerShell commands are defined in the XML to obtain status and detail information for the security component.

To create an .xml file

Open Notepad.
Add the following XML data to the new file to define the name and application for the security component.
```
<?xml version="1.0" encoding="utf-8" ?>
<FeatureList>
    <Feature Name="Windows Firewall" Source="MpsSvc">
    </Feature>
</FeatureList>
```
The Name attribute of the Feature Element defines the name that will be displayed in the Security Essentials column. The Source attribute of the Feature element defines the name of the application that is being monitored and will be displayed in the Source column. For this example, the MpsSvc service for the Windows Firewall is used as the application to monitor.

Note

You can add multiple Feature elements to a FeatureList Element to define multiple security components.

To add the health check for the security component

The HealthChecks Element is added to the Feature element to define the status information for the security component. The status represents the health state of the security component. Add the following XML data to the file to retrieve status information for the security component.
```
<HealthChecks>
    <HealthCheck Type ="PowerShell">
        <Script>
            $(Get-Service MpsSvc).Status -eq "Running"
        </Script>
        <ResultTrue Status="Ok" 
            Detail="The service is running."/>
        <ResultFalse Status="Critical" 
            Detail="The service is not running. Try restarting the service."/>
    </HealthCheck>
</HealthChecks>
```
The Type attribute of the HealthCheck Element defines the method by which status information will be obtained. Status information can be obtained using a Windows PowerShell script or using a C# class. For more information about creating an add-in using C#, see Walkthrough: Creating a Security Add-in Using XML and PowerShell. The Script Element defines the Windows PowerShell commands to run for the security component.

In this example, the PowerShell script returns a value of True if the Windows Firewall service is running; otherwise, False. If the return value is True, the ResultTrue Element is used to display the status; otherwise, the ResultFalse Element is used. The Status attribute can be one of the following values:
- Ok
- Warning
- Critical
- NotInstalled
- NotApplicable
- Unavailable
You can also use a COM object to retrieve additional information about the Windows Firewall service. Add the following HealthCheck element to the XML data in the file to retrieve information about whether the Windows Firewall is enabled.
```
<HealthChecks>
    <HealthCheck Type="PowerShell">
        <Script>
            $firewallObject=new-object -com HNetCfg.FwMgr
            $firewallObject.LocalPolicy.CurrentProfile.FirewallEnabled
        </Script>
        <ResultTrue Status="Ok" 
            Detail="Windows Firewall is enabled" />
        <ResultFalse Status="Warning" 
            Detail="Windows Firewall is not enabled" />
    </HealthCheck>
</HealthChecks>
```
The HealthChecks element can contain multiple HealthCheck elements. The worst health condition returned from a HealthCheck script will override all of the other health checks defined in the HealthChecks element. If the health state of the security component is Critical, the status will be displayed on the Security tab and will also be displayed in the Security section on the Home tab of the Windows SBS Console.

Note

The HealthChecks element is not required. If the HealthChecks element is not added, the status for the security component will be displayed as Unavailable.

To add the detail information about the security component

The DetailGroups Element is added to the Feature element to define the detail information for the security component. Add the following XML data to the file to retrieve detail information for the security component.
```
<DetailGroups>
    <DetailGroup Type="PowerShell">
        <InitializationScript>
            $firewallObject = new-object -com HNetCfg.FwMgr
            $currentPolicy = $firewallObject.LocalPolicy.CurrentProfile
        </InitializationScript>
        <Detail Title="Firewall Enabled" 
            ValueScript="$currentPolicy.FirewallEnabled"/>
        <Detail Title="Exceptions Prevented"
            ValueScript="$currentPolicy.ExceptionsNotAllowed"/>
        <Detail Title="Inbound ICMP Allowed"
            ValueScript="$currentPolicy.IcmpSettings.AllowInboundEchoRequest"/>
        <Detail Title="Services Allowed"
            ValueScript="$currentPolicy.Services | foreach-object {$_.Name}"/>
    </DetailGroup>
</DetailGroups>
```
The Detail Element will be displayed as two columns in the details pane. The first column contains the Title attribute that represents the label of the detail item and the second column contains the ValueScript attribute which displays the detail information from the security component. In this example, the following information is displayed:
- The status of the Windows Firewall service.
- Whether or not exceptions are allowed to the firewall settings.
- Whether or not inbound echo requests are allowed through the firewall.
- The list of services of the Windows Firewall.

To add help information for the security component

The Help Element is added to the Feature element to define a short description for the security component that is being added. This information will be displayed in the details pane of Windows SBS Console when the component is selected. Add the following XML data to the file to provide information for the security component.
```
<Help>
   Information for the security component goes here.
</Help>
```
Save the .xml file. You can provide any meaningful name to the file, but it must have a .xml extension.

The following example shows the complete XML data for the security component.

<?xml version="1.0" encoding="utf-8" ?>
<FeatureList>
    <Feature Name="Windows Firewall" Source="MpsSvc">
       <HealthChecks>
          <HealthCheck Type ="PowerShell">
             <Script>
                $(Get-Service MpsSvc).Status -eq "Running"
             </Script>
             <ResultTrue Status="Ok" 
                Detail="The service is running."/>
             <ResultFalse Status="Critical" 
                Detail="The service is not running. Try restarting the service."/>
         </HealthCheck>
      </HealthChecks>
      <DetailGroups>
         <DetailGroup Type="PowerShell">
            <InitializationScript>
               $firewallObject = new-object -com HNetCfg.FwMgr
               $currentPolicy = $firewallObject.LocalPolicy.CurrentProfile
            </InitializationScript>
            <Detail Title="Firewall Enabled" 
               ValueScript="$currentPolicy.FirewallEnabled"/>
            <Detail Title="Exceptions Prevented"
               ValueScript="$currentPolicy.ExceptionsNotAllowed"/>
            <Detail Title="Inbound ICMP Allowed"
               ValueScript="$currentPolicy.IcmpSettings.AllowInboundEchoRequest"/>
            <Detail Title="Services Allowed"
               ValueScript="$currentPolicy.Services | foreach-object {$_.Name}"/>
         </DetailGroup>
      </DetailGroups>
      <Help>
         Information for the security component goes here.
      </Help>
   </Feature>
</FeatureList>

After you have created the .xml file, you can deploy it to the server.

Deploying a Security Add-in

In this section, you will place the .xml file that you previously created in the directory where the Windows SBS Console and Windows SBS Manager service can locate it, and you will verify that the security add-in is functioning correctly.

To deploy the security add-in

Copy the .xml file that was created earlier in this document to the %programfiles%\Windows Small Business Server\Data\SHExtensions directory on the computer that is running the Windows SBS 2008 operating system.
Open the Windows SBS Console, and then click the Security tab.
Verify that your new security add-in is functioning correctly by reviewing the entry for your security component.