Merge pull request #2042 from jan-cerny/autotailor_doc

Update documentation of autotailor

Author: evgenyz

docs/manual/manual.adoc

@@ -77,7 +77,7 @@ and {usgcb}[USGCB].
 You can also generate your own SCAP content if you have an understanding of at
 least XCCDF or OVAL. XCCDF content is also frequently published online under
 open source licenses, and you can customize this content to suit your needs
-instead. SCAP Workbench is a great tool to do the customization.
+instead.
 
 == Installing OpenSCAP
 
@@ -2210,10 +2210,17 @@ OSCAP_REMEDIATE_VERBOSE_LEVEL=INFO
 
 The downloaded guidance contains rule descriptions, but it doesn't contain OVAL checks which could be used for evaluation by OpenSCAP. You can find guidances with implemented OVAL checks and also with remediations at https://github.com/ComplianceAsCode/content[ComplianceAsCode] project, which contains wide range of profiles.
 
+*How can I create a tailoring file if I can't install SCAP Workbench?*
+
+Use the `autotailor` tool which allows you to create tailoring files using command line options.
+For more information, please refer to section <<_tailoring,Tailoring>>.
+
 *I try to apply a tailoring file, but OpenSCAP still evaluates rules that I have unselected. How can I enforce my changes of the profile?*
 
 Make sure that you provide the ID of the customized profile in `--profile` option instead of the ID of the original profile.
-If you created the tailoring file using SCAP Workbench, you were prompted to choose the ID of the customized profile. You can display the ID of the customized profile by running `oscap info <your_tailoring_file>`. By default, the ID of the customized profile ends with `_customized` suffix.
+If you created the tailoring file using `autotailor` and you haven't used the `-p` or `--new-profile-id` option, the ID of the customized profile is the original profile ID with `_customized` suffix appended.
+If you created the tailoring file using SCAP Workbench, you were prompted to choose the ID of the customized profile. By default, the ID of the customized profile is the original profile ID with `_customized` suffix appended.
+You can find the ID of the customized profile with `oscap info <your_tailoring_file>` command.
 
 *My SCAP source data stream contains rule `security_patches_up_to_date` which needs to download some data from the internet to work.*
 *But I'm in an air gapped environment so it can't download it.*

utils/autotailor.8

@@ -1,4 +1,4 @@
-.TH autotailor "8" "April 2020" "Red Hat, Inc." "System Administration Utilities"
+.TH autotailor "8" "October 2023" "Red Hat, Inc." "System Administration Utilities"
 .SH NAME
 autotailor \- CLI tool for tailoring of SCAP data streams.
 .SH DESCRIPTION
@@ -11,6 +11,53 @@ The tool requires data stream location and ID of the base profile as inputs.
 Note however, that the referenced data stream is not opened, and the validity of tailoring is not checked against it.
 The tool doesn't prevent you from extending non-existent profiles, selecting non-existent rules, and so on.
 
+.SH SYNOPSIS
+autotailor [OPTION...] DATASTREAM_FILE BASE_PROFILE_ID
+
+.SH OPTIONS
+.TP
+\fB--title TITLE\fR
+.RS
+Title of the new profile.
+.RE
+.TP
+\fB--id-namespace ID_NAMESPACE\fR
+.RS
+The reverse-DNS style string that is part of entities IDs in the corresponding data stream. If left out, the default value 'org.ssgproject.content' is used.
+.RE
+.TP
+\fB-v VAR=VALUE, --var-value VAR=VALUE\fR
+.RS
+Specify modification of the XCCDF value in form <varname>=<value>. Name of the variable can be either its full name, or the suffix, in which case the 'xccdf_<id-namespace>_value' prefix will be prepended internally. Specify the argument multiple times if needed.
+.RE
+.TP
+\fB-r RULE=ROLE, --rule-role RULE=ROLE\fR
+.RS
+Specify refinement of the XCCDF rule role in form <rule_id>=<role>. Name of the rule can be either its full name, or the suffix, in which case the 'xccdf_<id-namespace>_rule_' prefix will be prepended internally.
+The value of <role> can be one of full, unscored, unchecked. Specify the argument multiple times if needed.
+.RE
+.TP
+\fB-e RULE=SEVERITY, --rule-severity RULE=SEVERITY\fR
+.RS
+Specify refinement of the XCCDF rule severity in form <rule_id>=<severity>. Name of the rule can be either its full name, or the suffix, in which case the 'xccdf_<id-namespace>_rule_' prefix will be prepended internally. The value of <severity> can be one of unknown, info, low, medium, high. Specify the argument multiple times if needed.
+.RE
+.TP
+\fB-s RULE_ID, --select RULE_ID\fR
+.RS
+Specify the rule to select. The rule ID can be either full, or just the suffix, in which case the 'xccdf_<id-namespace>_rule' prefix will be prepended internally. Specify the argument multiple times if needed.
+.RE
+.TP
+\fB-u RULE_ID, --unselect RULE_ID\fR
+.RS
+Specify the rule to unselect. The argument works the same way as the --select argument.
+.RE
+.TP
+\fB-p NEW_PROFILE_ID, --new-profile-id NEW_PROFILE_ID\fR
+.RS
+Specify the ID of the tailored profile. The ID of the new profile can be either its full ID, or the suffix, in which case the 'xccdf_<id-namespace>_profile_' prefix will be prepended internally.
+If left out, the new ID will be obtained by appending '_customized' to the tailored profile ID.
+.RE
+
 .SH USAGE
 .SS Modify a variable value
 $ autotailor --var-value xccdf_org.ssgproject.content_value_var_screensaver_lock_delay=120 -o tailoring.xml ssg-rhel8-ds.xml xccdf_org.ssgproject.content_profile_pci_dss
@@ -27,8 +74,6 @@ The tailoring tailoring_file defines a new profile, xccdf_org.ssgproject.content
 .SS Perform more modifications
 $ autotailor --var-value var_screensaver_lock_delay=120 --select gconf_gnome_screensaver_idle_delay --var-value inactivity_timeout_value=600 ssg-rhel8-ds.xml pci_dss
 
-Use the --help option to learn about other options and their usage.
-
 .SH REPORTING BUGS
 .nf
 Please report bugs using https://github.com/OpenSCAP/openscap/issues