Compliance standard framework

BMC Database Automation (BDA) provides a platform for implementing compliance standards for your environment. Built on Actions, a framework for automating tasks and running scripts on hosts and databases, standards check hosts and databases for compliance, and also corrects hosts and databases that do not meet individual compliance standards.

A standard is a specially constructed Action that contains code that implements a set of compliance rules (also known as checks) and reports back to the BDA Manager whether the rules have been met by calling perl libraries embedded in the BDA agent. Because this can be a complex process, BMC provides a compliance library and runme/runme.bat executables (collectively known as the BDA Compliance Standard Framework) that can be included in a standard. This framework makes it easier to implement compliance rules by handling all the communication with BDA, so that the user only needs to perform the compliance check itself.

Standards written using this framework contain directories to separate the different pieces of the standard, XML files that describe the individual rules, and executables (such as a perl script or an operating system command) that perform the checks. For example, for BMC’s DISA standard for an Oracle 11g database, the standard contains two scripts (runme and perl/runme.pl) and several perl libraries (perl/libs/*) that implement the framework for running the checks, and a directory that stores all the compliance rules.

The directory that contains compliance rules is configured through a SUITE custom field in the standard’s template that contains the name of directory where compliance checks are stored.The following example illustrates a file that defines a SUITE custom field which directs the standard to search for compliance rules in the SKEL directory.

<?xml version="1.0" encoding="utf-8"?>
<defaults>

	<custom_fields>
      <field>
		   <name>SUITE</name>
		   <value>SKEL</value>
           <required>true</required>
		   <hidden>true</hidden>
   	  </field>
	 </custom_fields>

    <editable>

    <non_editable>
 
</defaults>

Custom fields

Because standards are specially constructed actions, they can use custom fields in  BDA actions.  For more information on how to use custom fields in your standards, see Adding custom fields to a template.

The BDA compliance standard framework uses two reserved custom fields to define special behavior:

• SUITE. This field defines the name of the directory in the standard where compliance checks are stored. If this field only has one value, it should be hidden, but if it has several possible values, they should all be specified in the template so that they can be selected in a menu. If the value of this field does not map to a directory in the standard, the standard will not run.

• EXCLUDED_CHECKS. This optional field is a comma-separated list of check <id>s that will be marked EXCLUDED from the standard. The following example template excludes checks check_01 and check_02 from the standard. They will appear in the Compliance Results page, but they will be labeled "EXCLUDED".

<?xml version="1.0" encoding="utf-8"?>
<defaults>
 
  <custom_fields>
    <field>
        <name>SUITE</name>
        <value>SKEL</value>
        <required>true</required>
        <hidden>true</hidden>
    </field>
 
    <field>
        <name>EXCLUDED_CHECKS</name>
        <value>check_01,check_02</value>
        <required>true</required>
        <hidden>true</hidden>
    </field>
  </custom_fields>
 
  <editable/>
 
  <non_editable/>
 
</defaults> 

All special custom fields are processed by the perl/runme.pl file that is included in the BDA compliance standard framework.

Rules

Rules evaluate an object (for example, a database) against a pre-defined test. In standards that use the BDA compliance standard framework, each rule has a corresponding .xml file that describes what the rule does.

For example, a DISA standard for an Oracle 11g database might require 64 different checks to comply with that standard. The following example shows the format of the .xml file for one of those individual checks:

<?xml version="1.0" encoding="utf-8"?>
<check>
	<name>DBMS application object owner accounts</name>
	
	<id>DG0004</id>
	
	<description>Application object owner accounts should be disabled 
				 when not performing installation or maintenance 
				 actions.</description>
	
	<detect method="perl-script">runme.pl</detect>
	
	<recommendation>Disable any application object owner accounts.
					From SQL*Plus:alter user [username] account lock;
					Enable application object owner accounts only for 
					installation and maintenance. DBA are special purpose 
					accounts and do not require disabling although they 
					may own objects. For application objects that require 
					routine maintenance, e.g. index objects, to maintain 
					performance, consider allowing a special purpose 
					account to own the index or enable the application 
					owner account for the duration of the routine 
					maintenance function only.</recommendation>
</check>

The following table details the description of tags the <check> block.

Detect methods

The BDA compliance standard framework supports four check detection methods: perl-script, script, command, and manual.

perl-script

This detection method is one of two that provides the most flexibility in reporting the results of a check. It supports five different status codes:

• COMPLIANT
• NON COMPLIANT
• COMPLIANT_WITH_EXCEPTIONS
• INDETERMINATE
• MANUAL

For more information about status codes, see Viewing the results of a compliance standard.

script

This detection method also provides the most flexibility in reporting the results of a check, but it also allows you to author checks in any scripting or programming language.

Whichever language you use, the script must be executed from a command line on the target operating system:

• In UNIX-like OSs, include the proper execute permissions and ensure that the script has either a binary executable or a properly constructed shebang (#!) line.
• On Windows operating systems, the script must have an extension that is is recognized by cmd.exe as an executable.

This method supports the same five different status codes:

• COMPLIANT – exit code 10
• NON COMPLIANT – exit code 13
• COMPLIANT_WITH_EXCEPTIONS – exit code 12
• INDETERMINATE – exit code 0
• MANUAL – exit code 11

By exiting with one of these numeric exit codes, the script can communicate the status of the check.  The reason for the check result can be communicated by the script by writing a summary.txt file in the directory indicated by the GA_LOG_DIR environment variable.

command

This detection method allows you to specify a command to perform the check.  If the command exits with a non-zero exit code, the check fails with a NON COMPLIANT result.  If the command exits with a zero exit code, the check succeeds with a COMPLIANT result.

<?xml version="1.0" encoding="utf-8"?>
<check>
  <id>check_04</id>
  <name>Check #04</name>
  <description>Check to see whether the /etc/redhat-release exists</description>
  <detect method="command">ls /etc/redhat-release</detect>
  <recommendation>File should exist</recommendation>
</check> 

manual

This detection method allows you to specify that a check must be performed manually and marked compliant in the BDA GUI. The value of the detect tag is returned as the reason for the result of the check, and the result returned for the check is MANUAL.

Example standard

The following section illustrates a standard created from scratch. The following screen illustrates a downloaded standard into a system working directory:

Note the runme and runme.bat files. These files are the files that get executed when BDA runs the standard (runme is executed if the standard is run on a UNIX-like operating system, runme.bat is executed if the standard is run on a Windows operating system). The templates directory contains at least one XML file which, just like it does for BDA Actions, defines whatever custom variables are needed for the standard to run. The perl directory contains all the code that comprises the BDA compliance standard framework and the included files, along with the runme and runme.bat files, should not be modified or moved.

The SKEL directory is a sample directory containing three sample checks. The name of the directory is specified by the value of the SUITE custom field in the template. This custom variable is the only variable that is required to be in each template used by the BDA compliance standard framework. Wiithout it, the framework would not be able to determine in what directory the checks reside.

Each of the checks is specified by an XML file and a directory:

The names of the XML files and the names of the directories are the same. Although this is not required, it is a best practice for tracking purposes.

The following example shows the XML for the first check:

<?xml version="1.0" encoding="utf-8"?>
<check>
  <id>check_01</id>
  <name>Check #01</name>
  <description>This is a dummy check. It always compliant.</description>
  <detect method="perl-script">passme.pl</detect>
  <recommendation>N/A</recommendation>
</check>

Note that the contents of the <id> tag of the check is the same as the name of the directory for the check. This is how the BDA compliance standard framework determines what directory to pull files from when executing the check.

The <name> and <description> of the check are strings to identify the check, and the <recommendation> is the string that is displayed to the user if the check fails. The crucial part of this file is the <detect> tag.  It specifies the name of a file in the check_01 directory that will be executed to perform the check, and the method attribute tells the framework that this file is a perl script, shown in the following example:

use strict;
use warnings;
 
use ComplianceUtils;
 
pass_compliance("This check always succeeds"); 

This script starts using strict and warnings (which is always a best practice when writing perl scripts) and then uses the ComplianceUtils module of the BDA compliance standard framework. Next, it calls the pass_compliance() subroutine exported by that module.

The second check works in much the same way:

<?xml version="1.0" encoding="utf-8"?>
<check>
  <id>check_02</id>
  <name>Check #02</name>
  <description>This is a dummy check. It always non-compliant.</description>
  <detect method="perl-script">failme.pl</detect>
  <recommendation>N/A</recommendation>
</check>

use strict;
use warnings;
 
use ComplianceUtils;
 
fail_compliance("This check always fails"); 

The script uses strict, warnings and ComplianceUtils, and then it calls the the fail_compliance() subroutine exported by ComplianceUtils.

The following example shows how the third check performs:

<?xml version="1.0" encoding="utf-8"?>
<check>
  <id>check_03</id>
  <name>Check #03</name>
  <description>Check to see whether the specified files exist</description>
  <detect method="perl-script">files_exist.pl</detect>
  <recommendation>File(s) should exist</recommendation>
</check>

use strict;
use warnings;
 
# because we want to import an additional subroutine, we
# specify :DEFAULT (to import all the default subroutines)
# and then the name of the sub we're importing
use ComplianceUtils qw( :DEFAULT parameter_to_list );
 
my @files = parameter_to_list('LIST_OF_EXISTING_FILES');
 
die "The rule didn't get list of files to check"
    unless scalar @files;
 
foreach my $file (@files) {
    fail_compliance("File '$file' doesn't exist")
        unless -f $file;
}
pass_compliance("All files from the input list exist");

This third check looks for a custom parameter called LIST_OF_EXISTING_FILES that should contain a comma-separated list of files to look for. It uses the ComplianceUtils' parameter_to_list() function to convert the comma-separated list into an array.  If there are no files in the array, the rule calls die() to exit abnormally (this will fail the check). It then runs through the array and checks to see if each of the files exists. If any of them do not exist, the rule calls fail_compliance() to fail the check. If it finds all the files in the array, and it calls pass_compliance() to mark the check as passed.

However, because this check relies on a custom parameter being defined, that custom parameter needs to be in the template used for this standard, as shown in the following example:

<?xml version="1.0" encoding="utf-8"?>
<defaults>
  <custom_fields>
    <field>
      <name>SUITE</name>
      <value>SKEL</value>
      <required>true</required>
      <hidden>true</hidden>
    </field>
 
    <!-- required for check_03 -->
    <field>
      <name>LIST_OF_EXISTING_FILES_DESCRIPTION</name>
      <value>
A comma-separated list of files that should exist on target node.
Example: /etc/file1, /etc/file2
Affects: check_03</value>
      <editable>false</editable>
    </field>
 
    <field>
      <name>LIST_OF_EXISTING_FILES</name>
      <value>/etc/redhat-release</value>
      <type>textarea</type>
    </field>
  </custom_fields>
 
  <editable>
    <notification_emails/>
  </editable>
 
  <non_editable/>
</defaults>

Lines 4-9 define the SUITE custom field that tells the BDA compliance standard framework where to look for the rules, and then lines 21-25 define a LIST_OF_EXISTING_FILES parameter that has a default value and be presented in a textarea. The parameter defined in lines 12-19 are a read-only parameter (note that <editable> is set to false on line 18) that is used to describe to the user what the LIST_OF_EXISTING_FILES parameter is used for. Having a description for each parameter is not a requirement, but it is a best practice.

Changing the example

The SKEL directory can be renamed along with the value of the SUITE custom field in the template to be more appropriate for the standard you are trying to create.  Each individual check will need an XML file and directory within the SKEL directory (or whatever you change SKEL to) where the names of the directories match the values of the <id> tags in the XML files. And executable scripts (either perl scripts or shell/batch scripts) that are specified in the XML file will need to be in the directory for each check. Do not change the runme, runme.bat or the contents of the perl directory.

Uploading your standard

The best way to upload all the files with the proper directories is to package all the files into a zip archive. Make sure that your archive doesn't contain a directory between the top level and your files. The runme, runme.bat, perl, templates, and your check directory should all be at the top level of the archive, as illustrated in the following screen:

When you create the standard in the BDA GUI, you can upload this zip file to load all the files into the correct place.

Where to go from here

Creating a compliance standard

Running a compliance standard

Running compliance reports

Additional resources

BDA Compliance Standard Framework

Customizing a Standard Developed by BMC