From 0be8d49fd97bdace0581aa7f7ebf295327301377 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C4=8Cern=C3=BD?= Date: Tue, 10 Oct 2023 08:33:54 +0200 Subject: [PATCH 1/2] Update documentation of autotailor - Refresh User Manual - Add missing Synopsis and Options sections to the man page The goal of this activity is to make sure `autotailor` is documented. Fortunately, there is already a great section "Tailoring" in the User Manual that covers `autotailor` well. --- docs/manual/manual.adoc | 11 +++++++-- utils/autotailor.8 | 51 ++++++++++++++++++++++++++++++++++++++--- 2 files changed, 57 insertions(+), 5 deletions(-) diff --git a/docs/manual/manual.adoc b/docs/manual/manual.adoc index 77f7b32e45..5b067cf3cb 100644 --- a/docs/manual/manual.adoc +++ b/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 on command line. +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 `. 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 display the ID of the customized profile by running `oscap info `. *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.* diff --git a/utils/autotailor.8 b/utils/autotailor.8 index c2299f4bae..46ceb75a3c 100644 --- a/utils/autotailor.8 +++ b/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...] DS_FILENAME 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 =. Name of the variable can be either its full name, or the suffix, in which case the 'xccdf__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 =. Name of the rule can be either its full name, or the suffix, in which case the 'xccdf__rule_' prefix will be prepended internally. +The value of 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 =. Name of the rule can be either its full name, or the suffix, in which case the 'xccdf__rule_' prefix will be prepended internally. The value of 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 what rules to select. The rule ID can be either full, or just the suffix, in which case the 'xccdf__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 what rules 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__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 From fce4223066aa4d1086ba06b3948a64a88939007b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C4=8Cern=C3=BD?= Date: Tue, 17 Oct 2023 10:36:20 +0200 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Evgeny Kolesnikov --- docs/manual/manual.adoc | 4 ++-- utils/autotailor.8 | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/manual/manual.adoc b/docs/manual/manual.adoc index 5b067cf3cb..e84babe421 100644 --- a/docs/manual/manual.adoc +++ b/docs/manual/manual.adoc @@ -2212,7 +2212,7 @@ The downloaded guidance contains rule descriptions, but it doesn't contain OVAL *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 on command line. +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?* @@ -2220,7 +2220,7 @@ For more information, please refer to section <<_tailoring,Tailoring>>. 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 `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 display the ID of the customized profile by running `oscap info `. +You can find the ID of the customized profile with `oscap info ` 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.* diff --git a/utils/autotailor.8 b/utils/autotailor.8 index 46ceb75a3c..5679f071d9 100644 --- a/utils/autotailor.8 +++ b/utils/autotailor.8 @@ -12,7 +12,7 @@ Note however, that the referenced data stream is not opened, and the validity of The tool doesn't prevent you from extending non-existent profiles, selecting non-existent rules, and so on. .SH SYNOPSIS -autotailor [OPTION...] DS_FILENAME BASE_PROFILE_ID +autotailor [OPTION...] DATASTREAM_FILE BASE_PROFILE_ID .SH OPTIONS .TP @@ -44,12 +44,12 @@ Specify refinement of the XCCDF rule severity in form =. Name .TP \fB-s RULE_ID, --select RULE_ID\fR .RS -Specify what rules to select. The rule ID can be either full, or just the suffix, in which case the 'xccdf__rule' prefix will be prepended internally. Specify the argument multiple times if needed. +Specify the rule to select. The rule ID can be either full, or just the suffix, in which case the 'xccdf__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 what rules to unselect. The argument works the same way as the --select argument. +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