We have received many requests to change our HTML report in some way. In this post I will try to summarize what it is people want to change and try to come up with a proposal for our new HTML report.
I started with the HTML report but the plan is to update both report and guide generators. They share a lot of code even today, it makes sense to update them both.
Problems with the current approach
openscap uses docbook as an intermediary format. This means that when generating guides or reports, the XCCDF is transformed into docbook using XSLT, that docbook is then transformed into XHTML. This causes several problems.
XCCDF allows XHTML in description, front-matter, rear-matter and others. We have to convert XHTML to pseudo-docbook and then back to XHTML. Data is inevitably lost during this transformation because docbook cannot possibly support all of XHTML.
Furthermore, the maintenance costs of such an arrangement are enormous. The XSLTs are big and hard to navigate through.
I believe benefits gained from using docbook are very small if there are any at all. There are serious issues when trying to generate PDF from our docbook guide/report which leads me to believe that nobody is using alternative output formats.
Requested features
Our users have requested several features and changes. I tried to gather some of them and list them here. If you have other suggestions please leave a comment!
- Rule filtering – for example to hide all passed rules
- Rule sorting – for example by severity, to form a remediation priority queue
- Rule full-text search – type CVEs, CCEs, titles, parts of descriptions, filter rules by them
- Custom branding – allow downstreams to insert their own logo
- Generate guide just for the chosen profile – as opposed to generating guide for the default profile
- Online XSLT used on demand for XCCDFs – could be hosted on open-scap.org and can be used to create reports on demand, OVAL details will be omitted if this arrangement is used
Must-have features
- Basic functionality even without any JavaScript in a modern HTML5-capable browser
- Provide all info we currently provide in our HTML report – especially OVAL details in failed rules
- “media: print” support
- Proper XHTML passthrough for description, front-matter, rear-matter and other XCCDF elements that allow XHTML
Design proposal
In my opinion we should base the new HTML guide and report on HTML5 and either Pattern Fly or Bootstrap, the project it’s based on. This should give us a starting point for visuals and usability. The new XSLT will no longer generate any docbook. Users that want PDF reports can generate them from the resulting HTML5.
The main problem with this is that we have to either bundle a lot of JavaScript and CSS, or fetch them from some remote site. From my estimates we would have to bundle ~200 kB with each guide and report. That seems quite excessive. I will try to bring the number down.
If that effort fails a reasonable compromise might be to bundle CSS and fetch JavaScript remotely if available. This means that open-scap.org would have to reliably host JavaScript resources for reports and guides. These would have to be frozen and versioned with diligence. Please note that even if the browser fails to load the JavaScript the basic functionality would still be available.
Prototype 1
What follows is a preliminary prototype. Not all planned functionality has been implemented.
I have used jQuery dataTables for search and sorting functionality. It supports pagination but I am unsure whether we want to use that or not.
Screenshots for the impatient:
Full archive of all the code for the rest:
Plans
I would like to get some feedback from the community before I continue with this research. If the feedback is positive I plan to start an experimental branch in the openscap upstream repository with the actual XSLTs.
I can make no promises but the ambitious plan is to have a new HTML report and guide in openscap 1.1.0.
See part 2.
Martin,
I like what you have started. I would suggest that errors get reported out in severity levels and not combined into an overall overall error status. I think it is important to see that I have no severe severity errors but may have several low severity errors.
Stated another way, instead of showing — 35% fail — how about — (0) 0% severe, (3) 10% major, (12) 25% minor — This would provide a quick overview of the number of errors and and the severity of those errors.
V/R,
Paul
I agree on both counts. The proposed design and initial prototype look good. Breaking out the failures by severity, or displaying this information somewhere, is desirable.
=1
Acknowleged, I will try to integrate this to the new report. Thanks for your feedback!
Under the overview, please add the ability to sort by Severity and Identifiers
Sort by severity is acknowledged, will add that.
What do you mean by sort by identifiers. What if the rule has more than 1 identifier? Even now you can sort by identifiers but it pretty much only takes the first identifier into account.
Could the rule name, not just XCCDF ID, be shown?
Rule name (called Title in XCCDF) is shown by default everywhere. It’s by far more readable than the ID. I only show rule ID in the panel. The Rule title is the title of the panel.
I don’t know anything about designing, but one of the functionalities that I’m missing is the ability to compare results of either multiple runs (history) as well as results against multiple targets.
Would it be possible to support this, given a set of result files?
That certainly is something we get asked a lot but IMO it’s out of scope of this particular task.
Having a functional semantic XCCDF result differ would be great. Then we can talk about visualising the diff itself, most probably reusing a lot of XSLT that will come from this project.
I am happy someone is looking at improving this area.
Another compromise for the js/css problem could be some lightweight js that dynamically loads the js/css to make all of the above an option. Have it look in the local directory, then the parent directory (so that there would only have to be one copy for anyone with many reports), and, if those fail, a hosted solution. Another command line option in openscap for exporting the js/css would logically follow.
I’ve been dismayed when trying to use either to generate HTML references to external documents or between s. Will the better support of XHTML obviate those problems?
Yes, the new HTML report will give you much more power in this regard. It basically copies elements that allow XHTML as they are, with no transformation being done.
That means it will have full support for all XHTML formatting in elements that allow it.
Apologies, I should have used entities:
s/use either/use <references> either/
s/between s/between <Rule>s/