I have successfully defended my Master Thesis at the Faculty of Informatics of Masaryk University in Brno. This page shall serve as a permalink for the thesis.
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.
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:
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.
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”.
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