SCE | OpenSCAP portal

Script Check Engine

Currently, many administrators use several of their own scripts to make sure their systems follow certain guidelines. These scripts are usually written in Bash and are executed as they are. The administrators would like to move to SCAP to allow them to inter-operate and use tools supporting these standards. However they can’t afford to make that transition abruptly, it would require them to rework all of their testing scripts at once.

Language support

One of the goals was to make it as simple as possible while not sacrificing flexibility. Therefore we chose to support everything that is executable from the command line. While we realize that this doesn’t enforce any standards and might make collaboration on check scripts harder, we believe that it’s up to the content creation projects to enforce these standards.

Examples of supported languages:

Bash, Python, Perl, Ruby

Usage

To reference your custom check scripts in XCCDF use the <check-content-ref> element with http://open-scap.org/page/SCE as the “system” attribute. The “href” attribute should contain the path to the script. The path should be either absolute or relative to the XCCDF file.

Reporting reasons when check fails

Usually, when a script fails, you want to know why that happened so that you can correct the cause. If the scripts only returned the final result, this would have been difficult. This is why we redirect stdout and stderr and capture the output. There are 2 possible ways to get the output:

1. use <check-import> element

The preferred way is to have a

<check-import import-name="stdout" />

element in the source XCCDF. This will fetch stdout from the Script Check Engine and put it in rule-result for later examination. XSLT transformations of openscap will see that the check-import is there and use that data. This is what we recommend content projects to adopt.

2. use SCE result file

In case there is no

<check-import import-name="stdout" />

in the XCCDF (or the XSLT can’t find it for whatever reason), it will try to look for SCE result files and get their stdout element content.

SCE result file

Just a single value from a check is not enough except for super simple checks. If a scripts checks permissions of files in your home directory and finds something wrong you want to know which files are the offenders so you can fix the situation quickly. This is why we store stdout/stderr output from scripts and allow user to interpret it.

The result file is an XML. The main reason for that is that we want to use it with XSLT transformation to aggregate OVAL and SCE results together to a HTML file or a PDF.

The most important and useful bit is inside the <stdout> element. This is what usually contains information on why exactly the check failed.

See the code

Examples

Here is a short example of using Script Check Engine in OpenSCAP. It is a simple rule checking that SELinux is in enforcing mode on a system.

Section of an XCCDF

In a XCCDF rule, you include a check element, that will contain a reference to external script.

...
<Rule id="rule-20" selected="true">
    <title>selinux</title>
    <description>
        <xhtml:pre xmlns:xhtml="http://www.w3.org/1999/xhtml">Checks if you have SELinux enabled</xhtml:pre>
    </description>
    <check system="http://open-scap.org/page/SCE">
        <check-import import-name="stdout" />
        <check-content-ref href="selinux.sh" />
    </check>
</Rule>
...

selinux.sh

The check itself is only a short bash script in a separate file. It returns either XCCDF_RESULT_FAIL or XCCDF_RESULT_PASS, depending on the check results.

#!/usr/bin/env bash

SELINUX_MODE=`/usr/sbin/getenforce`

if [[ $SELINUX_MODE != "Enforcing" ]]
then
	echo "Selinux is in "$SELINUX_MODE" mode."
	echo "Using Enforing mode is highly recommended. See selinux manual page for switching to Enforcing mode."

	exit $XCCDF_RESULT_FAIL
fi

exit $XCCDF_RESULT_PASS

Passing variables using <check-export>

XCCDF variables and operators are communicated to the check executable using environment variables. Please refer to the XCCDF specification for more info about how variables can be passed to checks – specifically the <check-export> element.

XCCDF_TYPE_${variable name} holds the type – “BOOLEAN”, “NUMBER” or “STRING”

XCCDF_VALUE_${variable name} holds the value payload.

XCCDF_OPERATOR_${variable name} holds the operator – “EQUALS”, “NOT_EQUALS”, “GREATER”, “GREATER_EQUAL”, “LESS”, “LESS_EQUAL” or “PATTERN_MATCH”.

It is recommended to create some sort of a reusable parser in your check scripts.

Enable SCE in OpenSCAP

OpenSCAP older than 1.3.0 doesn’t not contain SCE support by default, you have to use a configure command option to enable it. Packages of OpenSCAP generally have SCE enabled.

./configure --enable-sce

Since OpenSCAP version 1.3.0 SCE is built by default. Optionally, it can be turned off by setting CMake option ENABLE_SCE to OFF.

Since version 0.9.12 SCE is not part of libopenscap.so, but it is built separately into libopenscap_sce.so and optionally loaded as a optional plugin at runtime.

Package repository

If you are using OpenSCAP from your package repository, check whether you need to install a supplemental package. For example in Fedora the OpenSCAP SCE engine is packaged as “openscap-engine-sce”. To enable it, execute:

# dnf install openscap-engine-sce