Merge pull request #157 from matejak/doc-fix

Update user manual with the remediation role export feature

Author: mpreisler

doc/user_manual.adoc

@@ -380,6 +380,24 @@ to remediate each of them.
 
 The rules that were remediated will show up as *fixed* in the rule result list.
 
+=== Export remediation role for the selected profile
+
+After you select a profile, you can export a remediation role to a file.
+Bash scripts, Ansible playbooks and Puppet manifests are the formats supported.
+The output file will contain all remediations for rules selected by the profile
+that are available.
+As the content of the remediation role solely depends on the profile,
+it is referred to as profile-based remediation role.
+
+The possibility to save remediations to a file puts you in charge -
+you can examine it, edit it and decide what remediations to apply.
+However, the result-based remediations export produces output
+that fits your system better.
+See <<view-and-analyze-results>> to learn more about it.
+
+Be aware that remediations may not be implemented in all formats.
+The most widely supported formats are bash scripts and Ansible playbooks.
+
 === Evaluate
 
 Everything is set up we can now start the evaluation. Click the *Scan*
@@ -424,7 +442,8 @@ which will clear all results.
 
 === View and Analyze Results
 
-After evaluation finishes, you should see three new buttons: *Clear*, *Save Results* and *Show Report*.
+After evaluation finishes, you should see three new buttons:
+*Clear*, *Save Results*, *Generate remediation role* and *Show Report*.
 
 ****
 Pressing Clear will *permanently* destroy scan results! This action cannot
@@ -470,6 +489,17 @@ However, ARF files are not as well supported by SCAP toolchains as XCCDF result
 XCCDF result files can be generated from ARF files, this operation is called *ARF splitting*.
 ****
 
+Opening the *Generate remediation role* pop-up menu will let you to save
+result-based remediations to a file.
+The output file will contain all available remediations for rules
+that have failed the scan, so it should fit your needs better
+than profile-based remediations.
+As the saved content is based on actual scan results,
+it is referred to as results-based remediation role.
+
+If you scan with a customized profile, you may encounter an error -
+see <<known-issues>> for a workaround.
+
 == Notable shortcuts
 
 === Main Window
@@ -494,6 +524,20 @@ Both while opening the files and when scanning. This option is discouraged and
 should only be used by content creators and/or people who really know what they
 are doing.
 
+== Known issues
+
+=== Result-based remediations of tailored profiles
+
+Saving remediation roles to the disk may not work for a customized profile. Specifically, it won't work if you add additional rules to it.
+If this limitation affects you, follow these steps:
+
+Remark: You will need to use the oscap command-line utility, which is bundled together with scap-workbench.
+
+1. Save the scan results
+2. Save your profile customization to a file using the "File->Save customization only" option.
+3. Run this command: oscap xccdf generate fix --output <role filename> --result-id '' --tailoring-file <saved-customization> <saved-result>.
+Refer to oscap xccdf generate fix -h if you want other than Bash output.
+
 == Where to Get Help?
 
 You ask for help with the application using