Introduction

OpenSCAP 1.1.0 introduced brand new HTML5 report and guide styles. These were a result of an almost complete rewrite of all the XSLT code. See openscap HTML report redesign for more info.

This rewrite changed the way the reports and guides can be customized. This blog post will go through all the steps necessary to customize the reports from both the downstream packager perspective and the user perspective. We will focus on branding because this is the most requested customization. Users will be able to change the logo, header and footer of reports and guides.

Downstream branding

After installing openscap of version 1.1.0 or higher, let us look at various files in /usr/share/openscap/xslt.

$ ls -1 /usr/share/openscap/xsl/

legacy-fixtpl-bash.xml
legacy-fix.xsl
legacy-xccdf-share.xsl
oval-results-report.xsl
xccdf_1.1_remove_dangling_sub.xsl
xccdf_1.1_to_1.2.xsl
xccdf-branding.xsl
xccdf-guide-impl.xsl
xccdf-guide.xsl
xccdf-report-impl.xsl
xccdf-report-oval-details.xsl
xccdf-report.xsl
xccdf-resources.xsl
xccdf-share.xsl

The xccdf-report.xsl is the entry point to the XSLT stylesheet, it specifies which parameters are needed and does some initial negotiation like guessing which benchmark the user wants to generate for. The xccdf-report-impl.xsl is the most interesting file, it contains most of the logic. xccdf-share.xsl contains various template code needed in both guide and report, to avoid code duplication.

Let us focus on a file called xccdf-branding.xsl. This file was designed specifically to help with downstream branding. If we look inside we will see 5 named templates:

• xccdf-branding-logo
• xccdf-report-header
• xccdf-report-footer
• xccdf-guide-header
• xccdf-guide-footer

Their meaning should be self explanatory. The downstreams can patch those to insert a different logo or even different texts. Changes to this file will affect every user that runs oscap xccdf generate guide or oscap xccdf generate report.

Example of changed xccdf-report-header – different header:

<xsl:template name="xccdf-report-header">
    <nav class="navbar navbar-default" role="navigation">
        <div class="navbar-header" style="float: none">
            <a class="navbar-brand" href="#">
                <xsl:call-template name="xccdf-branding-logo"/>
            </a>
            <div><h1>Security Compliance Report</h1></div>
        </div>
    </nav>
</xsl:template>

Example of changed xccdf-report-footer – downstream ticket system hint:

<xsl:template name="xccdf-report-footer">
    <footer id="footer">
        <div class="container">
            <p class="muted credit">
                Please report any issues to the <a href="https://bugs.my-cool-distro.tld">ticket system</a>. Generated using <a href="http://www.open-scap.org">OpenSCAP</a>
                <xsl:if test="$oscap-version">
                    <xsl:value-of select="concat(' ', $oscap-version)"/>
                </xsl:if>
            </p>
        </div>
    </footer>
</xsl:template>

The OpenSCAP team would really appreciate if you kept some link to the upstream but the license does not enforce or even require that.

User branding

Sometimes you might want to change the branding just for this one use-case without affecting all users on the system.

This is not commonly used and as such may have more issues than when using the system-wide XSLTs!

Let us copy the XSLTs as they are into a folder where we will do all the changes we need.

cp -r /usr/share/openscap/xsl ~/custom-oscap-xsl
cd ~/custom-oscap-xsl

We can now do all the customizations similarly to the previous section. Lets change the header from OpenSCAP Evaluation Report to Security Compliance Report in xccdf-branding.xsl. Save the changes and proceed to generate a report. Instead of using oscap xccdf generate report we have to use oscap xccdf generate custom --stylesheet $OUR_STYLESHEET

cd ~/custom-oscap-xsl
oscap xccdf generate custom --stylesheet ~/custom-oscap-xsl/xccdf-report.xsl arf.xml > report.html
firefox report.html

We can see that the report has “Security Compliance Report” as heading instead of “OpenSCAP Evaluation Report”.

The oscap xccdf generate custom code path in the oscap tool does not offer as many parameters as generate report or generate guide do. There parameters may have to be passed in a different way, even hard-coded into the XSL template if necessary! It all depends on the use-case.

What about OpenSCAP 1.0.x?

The method outlined in User branding also works with OpenSCAP 1.0.x. While the new reports are not regularly tested with OpenSCAP 1.0.x they seem to work fine. Use at your own risk!

$ cd ~/custom-oscap-xsl
$ oscap --v
OpenSCAP command line tool (oscap) 1.0.11
Copyright 2009--2015 Red Hat Inc., Durham, North Carolina.
...

oscap xccdf generate custom --stylesheet ~/custom-oscap-xsl/xccdf-report.xsl arf.xml > report.html
firefox report.html