Hardening SUSE Linux Enterprise with OpenSCAP #
This document introduces you to auditing and hardening SUSE Linux Enterprise with OpenSCAP and the
SCAP Security Guide.
SUSE seeks to provide customers with quick and easy guides that can assist them in maintaining security compliance. Implementation of the settings contained within this guide without its prior testing in a non-operational environment is highly discouraged. The developers of these profiles and documentation have made reasonable efforts to ensure overall compliance. They assume no responsibility for its use by other parties, and make no guarantee, expressed or implied, about its quality, reliability or any other characteristic.
1 What are SCAP and OpenSCAP? #
SCAP stands for Security Content Automation
Protocol. It is a framework of specifications that support automated
configuration, vulnerability scanning, and policy compliance evaluation of systems deployed
in an organization. It also standardizes how vulnerabilities and security configurations are
communicated both to machines and human beings.
OpenSCAP is a collection of open source tools that implement the SCAP framework for Linux. SCAP is maintained by the National Institute of Standards and Technology (NIST) . OpenSCAP received the SCAP 1.2 certification by NIST in 2014.
2 Benefits #
The OpenSCAP tools, together with the SCAP Security Guide, can be used for auditing
your system in an automated way. The SCAP Security Guide implements security guidances
recommended by respected authorities. These security guidances are transformed into a
machine-readable format which then can be used by OpenSCAP and other tools.
3 Infrastructure Preparation #
Before installation and hardening, it is recommended to prepare your IT infrastructure for the implementation of the SCAP Security Guide. As a preparation, do the following steps approximately in the order mentioned:
Create an inventory of the hosts on which SCAP Security Guide will be installed.
Create an inventory of IT and business services that will be in the scope of the installation.
Split the inventory into a few groups, considering that the configuration of hosts belonging to a group will be identical.
Select the standard or profile you are planning to implement in your infrastructure. For example, you can use Security Technical Implementation Guide from Defense Information Systems Agency, Payment Card Industry Data Security Standard and Health Insurance Portability and Accountability Act.
For each group member, create a list of rules and recommendations you plan to implement. You should consider the following:
Preconditions necessary for some of the rules
Configuration parameters for each recommendation, if they exist
Recommendations to be applied manually
Recommendations to be applied automatically
Recommendations to be excluded
Additional security controls or measures will be implemented to address excluded recommendations
Create a test environment that simulates your environment. Use it as a reference before implementing the technology in your real environment. You should consider the following:
The remediation has to be executed more than twice, because:
The recommendations are executed in alphabetical order
Between some recommendations, there are dependencies
The operating system needs to be restarted after each pass
A 100% hardening is impossible, and you have to specify an acceptable level of risk for members of each group
NoteThe acceptable level is a number of rules that will show the result “not pass” in case of an audit. Document these rules and apply additional security controls to compensate for them.
Use the test environment to test new patches and new updates of SCAP Security Guide.
In case of an error during the remediation, you can try the following:
Apply the rule manually
Exclude the rule using tailoring and use an additional security control instead
Register a bug, providing details about the version of SCAP Security Guide, logs from execution and steps performed by you
Create an implementation plan covering your production environment.
Create backups.
4 Installation #
To use the OpenSCAP tools and the SCAP Security Guide for hardening your target system
by scanning and remediating vulnerabilities, install the following core packages:
openscap
openscap-utils
scap-security-guide
>sudozypper install openscap-utils scap-security-guide
For SUSE Linux Enterprise Micro, install using the following commands:
>sudotransactional-update pkg install openscap-utils scap-security-guide
>sudoreboot
These packages are dependencies for other optional packages discussed below.
Optionally, install the following packages:
scap-workbench: This package provides the SCAP Workbench graphical utility to perform common
oscaptasks.NoteThe scap-workbench package, being a GUI software, is available only for desktop installations of SUSE Linux Enterprise.
ssg-apply: When used along with SCAP Workbench, this package helps you conveniently apply a tailoring file for customized hardening.
>sudozypper install scap-workbench ssg-apply
As a security best practice, avoid installing an application software such as SCAP Workbench on the target system that you are planning to harden. Instead, install SCAP Workbench on a client machine and apply the hardening on the target system, while maintaining an air gap before the target system is connected to a potentially insecure network.
5 Important SCAP components #
SCAP consists of the following important components which interact with each other.
- Open Vulnerability and Assessment Language (OVAL)
An XML format for testing the presence of a specific state.
- Extensible Configuration Checklist Description Format (XCCDF)
An XML format that specifies security checklists, benchmarks and configuration documentation. The XCCDF file includes a benchmark as a set of different profiles related to different groups. Each group is a set of rules which have OVAL definitions. Each profile is related to different good practices such as STIG, HIPAA, PCI-DSS, or ANSSI.
- Common Platform Enumeration (CPE)
A structured naming scheme to identify information technology systems, platforms and software packages. It is maintained by NIST and NDV. The naming scheme consists of the following elements:
cpe:/part:vendor:product:version:update:edition:language- DataStreams (DS)
An XML format which packs different SCAP components (CPE, XCCDF, OVAL) into a single file. It can be used to distribute SCAP content over the network. The DataStreams files are useful because they include everything you need when you want to harden and audit your SUSE Linux Enterprise system.
- Common Configuration Enumeration (CCE)
Unique identifiers to security-related system configuration issues.
6 SCAP Security Guide content and directories #
SUSE ships the SCAP Security Guide (SSG) toolset in the
scap-security-guide package. It contains the latest set of security
polices for Linux systems. The SCAP Security Guide is maintained upstream in the
ComplianceAsCode
repository.
After you have installed the package, the SSG security content and the related files are available in your system from the following directories:
/usr/share/xml/scap/ssg/content/Contains the SSG security content. It consists of several Important SCAP components, which are all based on XML. All XML files in that directory are named according to the SCAP component and to the SUSE Linux Enterprise codestream they apply to (code 12 or 15). The directory also holds XML files specific to SUSE Linux Enterprise Micro and openSUSE.
You can view all available security policies by getting a list of datastream files:
>ls -l /usr/share/xml/scap/ssg/content/ssg-*-ds.xml/usr/share/doc/scap-security-guide/guides/Contains profiles for different hardening policies in human-readable format. They describe the profiles that are included in the DataStream files. The profiles applicable to SUSE Linux Enterprise are codestream-specific and differ between code 12 and code 15. Each profile is a guide on securing your operating system to ensure compliance with a regulation.
The guides usually have the following structure:
Short description
Profile Title. For example: DISA STIG for SUSE Linux Enterprise 15
Profile ID. For example: xccdf_org.ssgproject.content_profile_stig
Revision History. Information about the current version and status of the profile. For example: xccdf_org.ssgproject.content_profile_stig
Platforms (in CPE notation). Which product or system the profile applies to. For example: cpe:/o:suse:linux_enterprise_server:15
A table of contents
A checklist which consists of groups (and subgroups) with rules
Each rule consists of a short description, the rationale behind the rule, a severity (low, medium or high) and a unique identifier in the
Common Configuration Enumeration (CCE)format. The CCE number for each rule is provided to SUSE by NIST.Each rule also lists references to different good practices. For example, the rule known by the unique identifier
CCE-83289-9in STIG has a reference to a specific good practiceA.12.4.1in ISO/IEC 27001:2013.If remediation options exist for a rule, they are listed in different formats.
/usr/share/scap-security-guideContains subdirectories with fix scripts which can be used to remediate the target system in case a vulnerability is found during a scan. Fix scripts are available in the following two formats: Shell scripts (
bash/*.sh) and Ansible snippets (ansible/*.yml).
7 SCAP Security Guide profiles #
The SCAP Security Guide contains multiple profiles. The profiles applicable to SUSE Linux Enterprise are
codestream-specific and differ between code 12, code 15, and SLE Micro.
They are maintained and hosted at the following repositories:
https://github.com/ComplianceAsCode/content/tree/master/products/sle15/profiles
https://github.com/ComplianceAsCode/content/tree/master/products/sle12/profiles
https://github.com/ComplianceAsCode/content/tree/master/products/slmicro5/profiles
After the installation of the scap-security-guide package, human-readable
versions of the profiles are available in your file system in
/usr/share/doc/scap-security-guide/guides.
To list the guides for each profile in an HTML format, run the following command:
>ls -l /usr/share/doc/scap-security-guide/guides/ssg*.html
You can then see the guide related to a specific profile in your web browser. For example, to see the SLE 15 STIG profile using the Mozilla Firefox web browser, run the following command:
>firefox /usr/share/doc/scap-security-guide/guides/ssg-sle15-guide-stig.html
Alternatively, find the same content online as static HTML pages:
In the online versions, use the drop-down list in the upper-right corner of the page to select one of the available profiles and to view a command-line snippet about how to evaluate the respective profile with OpenSCAP.
7.1 Viewing information on SCAP Security Guide profiles #
Each security policy can have multiple profiles, which provide policies implemented according to specific security baselines. Every profile can select different rules and use different values. You can list these profiles using the following command format:
>oscap info /usr/share/xml/scap/ssg/content/ssg-OPERATING-SYSTEM-TYPE-OF-FILE.xml1
In the above command:
|
For example, you can view information about the ds files of
sle15 using the following command:
>oscap info /usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml
It is useful to know about some of the technical terms displayed in the output of the
oscap info command for ds and
xccdf files:
Document type. Describes what format the file is in. Common types include XCCDF, OVAL, Source Data Stream, and Result Data Stream.
Checklist version. The XCCDF version only shown for XCCDF files. Common values are
1.1and1.2.Imported. The date the file was imported for use with OpenSCAP. As OpenSCAP uses the local file system and has no proprietary database format, the imported date is the same as the file modification date.
Status. The XCCDF Benchmark status. Common values include "accepted", "draft", "deprecated", and "incomplete". Please refer to the XCCDF specification for details. This is only shown for XCCDF files.
Generated. The date the file was created. This date is shown for XCCDF files and Checklists, and is sourced from the XCCDF Status element.
Profiles. Available profile IDs that you can use for the
--profilecommand line attribute withoscap xccdf evalcommand.Checklists. Lists available checklists incorporated in the Data Stream that you can use for the
--benchmark-idcommand line attribute with theoscap xccdf evalcommand. Also, each checklist has detailed information displayed.
For example, for Security Technical Implementation Guide profiles, the following is relevant:
xccdf_org.ssgproject.content_profile_stig
7.2 SUSE Linux Enterprise 15 profiles #
For code 15, the following profiles are supported by SUSE:
ANSSI-BP-028 (enhanced)
ANSSI-BP-028 (high)
ANSSI-BP-028 (intermediary)
ANSSI-BP-028 (minimal)
CIS SUSE SUSE Linux Enterprise 15 Benchmark Level 2 (Workstation)
CIS SUSE Linux Enterprise 15 Benchmark for Level 1 (Server)
CIS SUSE Linux Enterprise 15 Benchmark for Level 1 (Workstation)
CIS SUSE Linux Enterprise 15 Benchmark for Level 2 (Server)
DISA STIG for SUSE Linux Enterprise 15
Hardening for Public Cloud Image of SUSE Linux Enterprise Server (SLES) for SAP Applications 15
Health Insurance Portability and Accountability Act (HIPAA)
PCI-DSS v4 Control Baseline for SUSE Linux Enterprise 15
Public Cloud Hardening for SUSE Linux Enterprise 15
Standard System Security Profile for SUSE Linux Enterprise 15
7.3 SUSE Linux Enterprise 12 profiles #
For code 12, the following profiles are supported by SUSE:
ANSSI-BP-028 (enhanced)
ANSSI-BP-028 (high)
ANSSI-BP-028 (intermediary)
ANSSI-BP-028 (minimal)
CIS SUSE SUSE Linux Enterprise 12 Benchmark Level 2 (Workstation)
CIS SUSE Linux Enterprise 12 Benchmark for Level 1 (Server)
CIS SUSE Linux Enterprise 12 Benchmark for Level 1 (Workstation)
CIS SUSE Linux Enterprise 12 Benchmark for Level 2 (Server)
DISA STIG for SUSE Linux Enterprise 12
PCI-DSS v.4 Control Baseline for SUSE Linux Enterprise 12
Standard System Security Profile for SUSE Linux Enterprise 12
7.4 SUSE Linux Enterprise Micro 5 profiles #
For SUSE Linux Enterprise Micro 5, the following profiles are supported by SUSE:
DISA STIG for SUSE Linux Enterprise Micro (SLEM) 5
Public Cloud Hardening for SUSE Linux Enterprise Micro (SLEM) 5
8 Customizing the SCAP Security Guide #
To customize the SCAP Security Guide for policies and profiles of your choice, perform the following steps:
Run the SCAP Workbench GUI software installed earlier.
#scap-workbenchSelect a variant for the target system—one of SLe12, SLe15, SLmicro5, then select Load Content.
Using the Profile drop-down list, select a profile with the desired policy, then select Customize.
Set a new ID for your custom profile. Set the ID in the following format:
xccdf_REVERSE-DNS_profile_REST-OF-THE-ID. For example,xccdf_org.mycorporation_profile_server.
WarningYou cannot change the ID of the custom profile later, using the SCAP Workbench.
Deselect the rules that you do not want in the custom profile. For example, you can deselect the following rule:
Record Events that Modify the System’s Discretionary Access Controls - chmod.To save the changes to the profile, select OK. The main guide window is displayed again.
To save only the customization, select Select customization file>Open>Save customization only. This creates a small file containing only the changes made to the original profile, and is called a customization or tailoring file. The advantage of this approach is that when a new version of the profile is available, you can simply apply your tailoring to it, instead of customizing it from scratch.
Alternatively, you can save the entire modified content in a directory. In that case, select the file, followed by Save all>Into a directory.
To use the customization file with the
oscapcommand-line tool, use the--tailoring-file NAME-OF-TAILORING-FILEoption. For example:#oscap xccdf eval \ --profile xccdf_org.ssgproject.content_profile_stig_customized \ --report report_sle15_stig.html \ --tailoring-file ssg-sle15-ds-tailoring.xml \ /usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml
9 Vulnerability scanning #
9.1 Targets to scan #
The content provided by the SCAP Security Guide can be used to scan the following
targets for vulnerabilities:
bare-metal machines
virtual machines
virtual machine images
containers
container images
Automated checks help to identify the target and to select only the rules that make sense for this specific target. For example, checks for separate partitions make sense for bare-metal machines but not for containers.
9.2 Tools for scanning #
Before using the tools described in this section, ensure that you have installed them as described in Section 4, “Installation”, as they are interdependent.
Depending on your setup and the target to scan (remote or local), you can use either of the following tools:
- oscap
A command-line interface that can be used to scan local machines. Both the openscap-utils and scap-security-guide package need to be installed on the local machine.
To understand the basic usage of
oscap, run it with the-hoption:>oscap -hoscap OpenSCAP command-line tool Usage: oscap [options] module operation [operation-options-and-arguments] Common options: --verbose <verbosity_level> - Turn on verbose mode at specified verbosity level. Verbosity level must be one of: DEVEL, INFO, WARNING, ERROR. --verbose-log-file <file> - Write verbose information into file. oscap options: -h --help - show this help -q --quiet - quiet mode -V --version - print info about supported SCAP versions Commands: ds - Data stream utilities oval - Open Vulnerability and Assessment Language xccdf - eXtensible Configuration Checklist Description Format cvss - Common Vulnerability Scoring System cpe - Common Platform Enumeration cve - Common Vulnerabilities and Exposures cvrf - Common Vulnerability Reporting Framework info - Print information about a SCAP file.To understand
oscapin greater detail, read its man pages by running theman oscap.- oscap-ssh
A command-line interface that can be used to scan a remote machine via SSH with an interface resembling the
oscaptool. On the local machine, the package openscap-utils needs to be installed. On the remote machine, the openscap-utils package needs to be installed.To understand the basic usage of
oscap-ssh, run it with the-hoption:>oscap -hoscap-ssh -- Tool for running oscap over SSH and collecting results. Usage: $ oscap-ssh user@host 22 info INPUT_CONTENT $ oscap-ssh user@host 22 xccdf eval [options] INPUT_CONTENT Only source data streams are supported as INPUT_CONTENT! supported oscap xccdf eval options are: --profile --tailoring-file --tailoring-id --cpe (external OVAL dependencies are not supported yet!) --oval-results --results --results-arf --report --skip-valid --skip-validation --fetch-remote-resources --local-files --progress --datastream-id --xccdf-id --benchmark-id --remediate $ oscap-ssh user@host 22 oval eval [options] INPUT_CONTENT supported oscap oval eval options are: --id --variables --directives --results --report --skip-valid --skip-validation --datastream-id --oval-id $ oscap-ssh user@host 22 oval collect [options] INPUT_CONTENT supported oscap oval collect options are: --id --syschar --variables --skip-valid --skip-validation specific option for oscap-ssh (must be first argument): --sudo To supply additional options to ssh/scp, define the SSH_ADDITIONAL_OPTIONS variable For instance, to ignore known hosts records, define SSH_ADDITIONAL_OPTIONS='-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null' specific option for oscap-ssh (must be first argument): See `man oscap` to learn more about semantics of these options.To understand
oscap-sshin greater detail, read its man pages by runningman oscap-ssh.- SCAP Workbench
SCAP Workbench is a graphical user interface for OpenSCAP. You can use it for convenience instead of using
oscap. For example, you can use SCAP Workbench for scanning a single machine, either local or remote (via SSH).To use SCAP Workbench, both the scap-workbench and scap-security-guide packages need to be installed on the local machine. On the remote machine, the openscap-utils package needs to be installed.
To start SCAP Workbench, run the following command:
>scap-workbench
Figure 4: SCAP Workbench #Although not recommended, you can invoke and perform certain basic operations by using SCAP Workbench as a command-line tool. To know more, read its man page by running
man scap-workbench.
9.3 Scanning a SUSE Linux Enterprise system #
The following example shows how to scan SUSE Linux Enterprise 15 locally with oscap for
vulnerability issues according to a certain profile. You can save the results in XML format
and generate an HTML report.
>oscapxccdf eval1 \ --profile stig2 \ --results /tmp/results.xml3 \ --report /tmp/report.html4 \ /usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml5
Calls the | |
Specifies the profile to use, in this case, | |
Saves the results of the evaluation to /tmp/results.xml. | |
Generates an HTML report called /tmp/report.html in addition to the results in XML. | |
Specifies the |
The evaluation process usually takes a few minutes, depending on the number of selected rules.
9.4 Evaluating with rules #
For each rule, we have the following fields:
Rule. For example, Install AIDE
Rule ID. For example, xccdf_org.ssgproject.content_rule_package_aide_installed
After determining the security policy and profile, use oscap xccdf eval
to perform an evaluation against them. For example, to evaluate the profile
xccdf_org.ssgproject.content_profile_stig and generate an HTML report,
you can use the following command format
#oscap xccdf eval \ --profile xccdf_org.ssgproject.content_profile_stig \ --report report_OPERATING-SYSTEM_stig.html \ /usr/share/xml/scap/ssg/content/ssg-OPERATING-SYSTEM-ds.xml1
Replace OPERATING-SYSTEM with either
|
To evaluate with a specific rule, you can specify the Rule ID using
the --rule command option. For example, you can evaluate only with the
rule xccdf_org.ssgproject.content_rule_package_aide_installed:
#oscap xccdf eval \ --profile xccdf_org.ssgproject.content_profile_stig \ --report report_OPERATING-SYSTEM_stig.html \ --rule xccdf_org.ssgproject.content_rule_package_aide_installed /usr/share/xml/scap/ssg/content/ssg-OPERATING-SYSTEM-ds.xml1
Replace OPERATING-SYSTEM with either
|
To evaluate without a specific rule, you can specify to skip the
Rule ID using the --skip-rule command option. For
example, you can evaluate without the rule
xccdf_org.ssgproject.content_rule_package_aide_installed:
#oscap xccdf eval \ --profile xccdf_org.ssgproject.content_profile_stig \ --report report_OPERATING-SYSTEM_stig.html \ --skip-rule xccdf_org.ssgproject.content_rule_package_aide_installed /usr/share/xml/scap/ssg/content/ssg-OPERATING-SYSTEM-ds.xml1
Replace OPERATING-SYSTEM with either
|
9.5 Using external or remote resources for scanning #
SCAP content may reference external resources. For example, the SCAP Security Guide uses an external OVAL
file to check whether the system is up to date and patched against known security
vulnerabilities. However, OpenSCAP can handle remote resources differently, based on the
options used while invoking the oscap command. In addition, you can use
strategies like downloading specific remote resources in advance, and pointing the
OpenSCAP tool towards the downloaded resources while invoking it.
9.5.1 Default warning for remote resources by OpenSCAP while performing evaluation #
While evaluating SCAP content with external resources, the OpenSCAP tool displays a warning. For example, OpenSCAP displays the following warning while performing the default evaluation of a system based on the SCAP Security Guide:
> oscap xccdf eval \
--profile xccdf_org.ssgproject.content_profile_stig \
--results ssg-sle15-xccdf-stig-results.xml \
/usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml
WARNING: Datastream component 'scap_org.open-scap_cref_pub-projects-security-oval-suse.linux.enterprise.15-
patch.xml.bz2' points out to the remote 'https://ftp.suse.com/pub/projects/security/oval/suse.linux.enterprise.
15-patch.xml.bz2'. Use '--fetch-remote-resources' option to download it.
WARNING: Skipping 'https://ftp.suse.com/pub/projects/security/oval/suse.linux.enterprise.15-patch.xml.bz2' file
which is referenced from datastream
WARNING: Skipping ./pub-projects-security-oval-suse.linux.enterprise.15-patch.xml.bz2 file which is referenced
from XCCDF contentThe following sections describe certain strategies to force OpenSCAP to fetch remote resources in real time, or download them in advance and use for evaluation and scanning the system.
9.5.2 Fetching remote resources for evaluation #
If you trust your local content and the remote content it references, you can use the
--fetch-remote-resources option to automatically download it when
invoking the OpenSCAP tool.
> oscap xccdf eval \
--fetch-remote-resources \
--profile xccdf_org.ssgproject.content_profile_stig \
--results ssg-sle15-xccdf-stig-results.xml \
/usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml
Downloading: https://ftp.suse.com/pub/projects/security/oval/suse.linux.enterprise.15-patch.xml.bz2 ... ok
--- Starting Evaluation —
...However, if access to the Internet is unavailable at the time of evaluation, or is considered a security risk, you can instruct OpenSCAP to use local files instead of remote resources.
9.5.3 Downloading and saving remote resources locally for evaluation #
On systems without Internet access, or in security sensitive deployments where OpenSCAP
cannot connect to the Internet, download the remote content using other tools and save it
locally. You can then pass it to OpenSCAP as a local file using the
--local-files option, instead of the
--fetch-remote-resources option.
For example, to prevent OpenSCAP from accessing the Internet but still use the patch file https://ftp.suse.com/pub/projects/security/oval/suse.linux.enterprise.15-patch.xml.bz2, perform the following procedure.
(Optional) Create a directory for storing the downloaded remote resources.
>mkdir ~/scap-files 1Directory to store downloaded remote resources. If you have identified a suitable directory, skip this step.
Download the remote resource and save it as a local file.
>wget -O ~/scap-files/pub-projects-security-oval-suse.linux.enterprise.15-patch.xml.bz21 \ https://ftp.suse.com/pub/projects/security/oval/suse.linux.enterprise.15-patch.xml.bz22NoteIn this example, the name of the local file is not arbitrary. Notice the following information in the SCAP source data stream file available at
/usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml:>cat /usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml | \ grep -n "scap_org.open-scap_cref_pub-projects-security-oval-suse.linux.enterprise.15-patch.xml.bz2" 17: <cat:uri name="pub-projects-security-oval-suse.linux.enterprise.15.xml" uri="#scap_org.open-scap_cref_pub-projects-security-oval-suse.linux.enterprise.15-patch.xml.bz2"/> 25: <ds:component-ref id="scap_org.open-scap_cref_pub-projects-security-oval-suse.linux.enterprise.15-patch.xml.bz2" xlink:href="https://ftp.suse.com/pub/projects/security/oval/suse.linux.enterprise.15-patch.xml.bz2"/>Run the evaluation using the local files downloaded earlier from the remote source.
>oscap xccdf eval \ --local-files ~/scap-files \ --profile xccdf_org.ssgproject.content_profile_stig \ --results ssg-sle15-xccdf-stig-results.xml \ /usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml WARNING: Using local file '~/scap-files/pub-projects-security-oval-suse.linux.enterprise.15-patch.xml.bz2' instead of 'https://ftp.suse.com/pub/projects/security/oval/suse.linux.enterprise.15-patch.xml.bz2' --- Starting Evaluation —TipDownload and use the specific files that are relevant for your SUSE Linux Enterprise product version, and avoid more generic ones. Being specific about the purpose and the files helps reduce the usage of server resources such as the processor, memory, storage and bandwidth. In addition, smaller file sizes also reduce the time required to complete the evaluation. For example, if you are interested only in SUSE Linux Enterprise 15 SP5, use the file available at https://ftp.suse.com/pub/projects/security/oval/suse.linux.enterprise.15-sp5-patch.xml.bz2.
Optionally, you can generate an HTML report from the XML results file.
>oscap xccdf generate report ssg-sle15-xccdf-stig-results.xml > ssg-sle15-xccdf-stig-report.htmlTipYou can generate an HTML report directly using the
oscap xccdf eval --reportoption, but separating the scan and the HTML report generation leads to less usage of server resources.
9.6 Scanning and auditing systems using OVAL files #
Using the OVAL content files for SUSE Linux Enterprise products, you can assess your SUSE Linux Enterprise systems and generate reports on the RPM package names and versions that are known to be affected by security issues in published CVEs.
The OVAL data provided by SUSE includes the following:
The patch-style OVAL data, which expresses all security updates on a patch level. These can include multiple CVEs per patch.
The vulnerability OVAL data, which expresses security vulnerabilities on a CVE level.
For detailed information on OVAL support provided by SUSE, refer to https://www.suse.com/support/security/oval/.
You can download OVAL files provided by SUSE from https://ftp.suse.com/pub/projects/security/oval/. As a best practice for scanning and auditing systems using OVAL files, perform the following procedure:
(Optional) Create a directory for downloading and storing remote resources.
>mkdir ~/oval-files 1Directory to store downloaded remote resources such as OVAL patch files. If you have identified a suitable directory, skip this step.
Download the remote resource and save it as a local file.
>wget -O ~/oval-files/suse.linux.enterprise.15-patch.xml.bz21 \ https://ftp.suse.com/pub/projects/security/oval/suse.linux.enterprise.15-patch.xml.bz22Run the evaluation using the local files downloaded earlier from the remote source.
>oscap oval eval \ --results sle15-oval-results.xml \ ~/oval-files/suse.linux.enterprise.15-patch.xml.bz2 \ Definition oval:org.opensuse.security:def:45435: false Definition oval:org.opensuse.security:def:45434: false Definition oval:org.opensuse.security:def:45433: false Definition oval:org.opensuse.security:def:45432: false Definition oval:org.opensuse.security:def:45431: false Definition oval:org.opensuse.security:def:45430: false Definition oval:org.opensuse.security:def:45429: false ... Evaluation done.TipDownload and use the specific files that are relevant for your SUSE Linux Enterprise product version, and avoid more generic ones. Being specific about the purpose and the files helps reduce the usage of server resources such as the processor, memory, storage and bandwidth. In addition, smaller file sizes also reduce the time required to complete the evaluation. For example, if you are interested only in SUSE Linux Enterprise 15 SP5, use the file available at https://ftp.suse.com/pub/projects/security/oval/suse.linux.enterprise.15-sp5-patch.xml.bz2.
Optionally, you can generate an HTML report from the XML results file.
>oscap oval generate report sle15-oval-results.xml > sle15-oval-report.htmlTipYou can generate an HTML report directly using the
oscap oval eval --reportoption, but separating the scan and the HTML report generation leads to less usage of server resources.
10 Vulnerability remediation #
The security policy profiles in the SCAP Security Guide can not only be used to scan a
target system and to generate reports, but also to automatically apply fixes to the target
system (remediation), if possible.
Automatic remediation is not offered in case the automatic application of a fix is too dangerous to be enforced in a running target system.
10.1 OpenSCAP remediation process #
OpenSCAP allows to automatically remediate target systems that have been found in a non-compliant state. This requires an XCCDF file with instructions. The overall process is as follows:
The
oscapcommand-line tool performs a system scan.Each rule that fails is marked as a candidate for remediation.
Within the XCCDF file,
oscapthen searches for an appropriate <xccdf:fix> element, resolves it, prepares the environment, and executes the fix script. The fix scripts can be either Bash*.shfiles or Ansible playbook*.ymlfiles.After the execution of the script, the respective rule is evaluated again to check if the fix was successful.
All results of the remediation are stored in an output XCCDF file.
10.2 OpenSCAP remediation options #
For remediating a target system with oscap, you have the following
options:
- Remediation on the fly
You can remediate a target system on the fly, while you are scanning it. In this case, evaluation and remediation are performed as a part of a single command. For details, see Section 10.4.1, “Remediating SUSE Linux Enterprise (on the fly)”.
- Remediation after scanning
You can remediate a target system after you have scanned it. In the first step, the system is only evaluated, and the results are stored in the XCCDF results file. In the second step,
oscapexecutes the fix scripts and verifies the result. For details, see Section 10.4.2, “Remediating SUSE Linux Enterprise (after scanning)”.- Review mode
The review mode allows to save remediation instructions to a file for further review. The remediation content is not executed during this operation. For details, see Section 10.4.4, “Storing SLE remediation instructions for review”.
10.3 Remediating for a specific profile using shell scripts #
For simple remediation of a profile without any condition, you can use the shell scripts that are shipped with the SCAP Security Guide.
Find the shell scripts that performs remediation without any condition:
>ls -l /usr/share/scap-security-guide/bash/The names of the scripts follow the format:
NAME-OF-PRODUCT-script-NAME-OF-PROFILE.sh.The supported products are as follows:
sle12,sle15, andslmicro5.The supported profiles are as follows:
stig,anssi_bp28_xxx,hipaa,pci-dss-4, andpcs-hardening.NoteThe standard profile is officially not supported.
Understand the format of the shell scripts and the rules within. In the scripts, each rule or recommendation maintains the following format:
Starts with
# BEGIN fix (CURRENT-NUMBER/TOTAL-NUMBER-OF-RULES) for RULE-IDEnds with
# END fix for RULE-ID.
Note: Exceptions to the rule formatThere are certain rules that contains a line ending with
IS MISSING!in between theBEGINandENDlines for a rule block. These rules do not have a remediation part; you have to do remediation manually if you want to apply it.Although the recommended approach for excluding rules from remediation is to use tailoring, you can also do it manually if there are bugs, or for tests. In that case, open the intended script with a text editor and comment out the necessary lines between
BEGINandENDfor a rule block.Make the script executable, and run it.
>sudo-schmod +x NAME-OF-PRODUCT-script-NAME-OF-PROFILE.sh>./NAME-OF-PRODUCT-script-NAME-OF-PROFILE.shNote: Reboot for SUSE Linux Enterprise MicroFor SUSE Linux Enterprise Micro, reboot the system after running the script. For example:
>sudo-schmod +x slmicro5-script-NAME-OF-PROFILE.sh>sudotransactional-update run ./slmicro5-script-NAME-OF-PROFILE.sh>sudoreboot
10.4 Remediating a SLE system with oscap #
The following examples show how to scan and remediate SUSE Linux Enterprise locally with
oscap to comply with a certain profile.
10.4.1 Remediating SUSE Linux Enterprise (on the fly) #
To remediate a system (on the fly), you can use a combination of --eval
and --remediate options of the oscap command. In this
case, the system is first scanned (audited), and then the command attempts to fix the
system. During the execution of the audit, you will see after each rule status as
pass, fail, or not applicable.
During the execution of the remediation, you will see the status as
fixed or error, after some of the rules.
>sudooscapxccdf eval --remediate1 \ --profile stig2 \ --results /tmp/results.xml3 \ --report /tmp/report.html4 \ --skip-rule xccdf_org.ssgproject.content_rule_accounts_authorized_local_users5 \ /usr/share/xml/scap/ssg/content/ssg-PRODUCT-NAME-ds.xml6
>sudoreboot
Calls the | |
Specifies the profile to use, in this case, | |
Saves the results of the evaluation to /tmp/results.xml. | |
Saves the report of the evaluation to /tmp/report.html. | |
Rules that you want to skip. | |
Specifies the |
In the resulting /tmp/results.xml file, the first
TestResult element shows the result of the scan
before the remediation. The second
TestResult element shows the result of the scan
after applying the remediation. In the second
TestResult element, if the result of a rule is
fixed, this means that the fix was successfully applied, and this
rule now passes evaluation. If the result of a rule is error, this
means that the remediation for this rule was not successful, and the rule still does
not pass evaluation.
>sudosudo transactional-update run oscap xccdf eval --remediate \ --profile stig \ --results /tmp/results_1.xml \ --report /tmp/report_1.html \ --skip-rule xccdf_org.ssgproject.content_rule_accounts_authorized_local_users \ /usr/share/xml/scap/ssg/content/ssg-slmicro5-ds.xml
>sudoreboot
>sudosudo oscap xccdf eval --remediate \ --profile stig \ --results /tmp/results_2.xml \ --report /tmp/report_2.html \ --skip-rule xccdf_org.ssgproject.content_rule_accounts_authorized_local_users \ /usr/share/xml/scap/ssg/content/ssg-slmicro5-ds.xml
>sudoreboot
--skip-rule option
In the above examples, the --skip-rule option is optional. However,
it is necessary to use it if you did not set the variable
var_accounts_authorized_local_users_regex. Otherwise, you will not
be able to do a sudo after reboot.
10.4.2 Remediating SUSE Linux Enterprise (after scanning) #
In this example, we first execute a scan and then run the remediation as next step.
>oscapxccdf eval1 \ --profile stig2 \ --results /tmp/results.xml3 \ /usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml4Calls the
oscap xccdfmodule and tells it to perform an evaluation.Specifies the profile to use, in this case,
stig.Saves the results of the evaluation as an XCCDF file to /tmp/results.xml.
Specifies the
SCAP Security Guidepolicy file to use. In this example, we use a policy file in theDataStreamformat that applies to SUSE Linux Enterprise code 15. To list all available policies, run:ls -1 /usr/share/xml/scap/ssg/content/ssg-*-ds.xml. For more information about a particular policy, runoscap infoon the file.During this step, the system is only evaluated, and the results are stored in a
TestResultelement in /tmp/results.xml.>oscapxccdf remediate1 \ --results /tmp/results.xml2 \ /tmp/results.xml3Calls the
oscap xccdfmodule and tells it to perform a remediation.Saves the results of the remediation to /tmp/results.xml.
Uses the /tmp/results.xml XCCDF file from the first step (evaluation) as input file.
During this step, the results file from the first step is used as input for the
oscapcommand. You can safely store the results from the second step in the same file that you use as input file, /tmp/results.xml. During this run,oscapcreates a newxccdf:TestResultelement in the file. The new element is based on the previous one and inherits all the data. The newly createdxccdf:TestResultelement differs only in therule-resultelements which failed in the first run. Only for those is the remediation executed.
10.4.3 Remediating systems using oscap and scripts #
To remediate a system, you have to generate a script that will fix the system. You have to decide in advance the profile and type of the script—bash or Ansible.
Before running the examples in this section, ensure that you have evaluated the system
using the oscap sccdf eval commands.
oscap and bash ##oscap xccdf generate fix --profile stig --fetch-remote-resources – fix-type bash --output GENERATED-BASH-REMEDIATION-SCRIPT-NAME.sh /usr/share/xml/scap/ssg/content/ssg-PRODUCT-NAME-ds.xml1
Replace PRODUCT-NAME with |
oscap and Ansible ##oscap xccdf generate fix --profile stig --fetch-remote-resources – fix-type ansible --output GENERATED-ANSIBLE-REMEDIATION-SCRIPT-NAME.yml /usr/share/xml/scap/ssg/content/ssg-PRODUCT-NAME-ds.xml1
Replace PRODUCT-NAME with |
oscap and bash ##oscap xccdf generate fix --profile stig --fetch-remote-resources – fix-type bash --output GENERATED-BASH-REMEDIATION-SCRIPT-NAME.sh /usr/share/xml/scap/ssg/content/ssg-slmicro5-ds.xml
oscap and Ansible ##oscap xccdf generate fix --profile stig --fetch-remote-resources – fix-type ansible --output GENERATED-ANSIBLE-REMEDIATION-SCRIPT-NAME.yml /usr/share/xml/scap/ssg/content/ssg-slmicro5-ds.xml
After running any of the above commands, you can run the generated script to remediate the system.
To execute remediation on SUSE Linux Enterprise Micro systems, you may need to run the remediation scripts more than once using the following command:
#transcational-update run GENERATED-BASH-REMEDIATION-SCRIPT-NAME.sh
10.4.4 Storing SLE remediation instructions for review #
You can also run oscap in review mode to store remediation
instructions to a file for further review. During this operation, the remediation content
is not executed. The following shows how to generate remediation
instructions in the form of a shell script:
>oscapxccdf generate fix1 \ --template urn:xccdf:fix:script:sh2 \ --profile stig3 \ --output my-remediation-script.sh4 \ /usr/share/xml/scap/ssg/content/ssg-sle15-ds.xml5
Calls the | |
Specifies the template to use, in this case, a shell script. | |
Specifies the profile to use, in this case, | |
Specifies the file to which the remediation instructions are written. | |
Specifies the |
10.5 Remediating a SLE system with Ansible #
You can use the Ansible playbooks provided by the SCAP Security Guide to remediate a
local system.
The ansible package is available from SUSE Package
Hub. Register your SUSE Linux Enterprise system and enable the SUSE Package
Hub extension. For SUSE Linux Enterprise 12, you additionally need to enable the Public
Cloud module. Then install the package with sudo zypper in
ansible.
For example, to remediate your system using the STIG Ansible playbook for SUSE Linux Enterprise 15
provided by the SCAP Security Guide, use the following command.
The following command alters the configuration of your system immediately. Make sure to test this thoroughly in a non-production system first.
> ansible-playbook -i "localhost," -c local \
/usr/share/scap-security-guide/ansible/sle15-playbook-stig.ymlAfter the playbook has finished, you are prompted to log in to your system, which is now compliant to the chosen policy.
10.6 Remediating for a specific profile using Ansible #
For simple remediation of a profile without any condition, you can use the shell scripts that are shipped with the SCAP Security Guide.
List the Ansible playbooks that are shipped with the SCAP Security Guide.
>ls -l /usr/share/scap-security-guide/ansible/The file names are in the following format:
NAME-OF-PRODUCT-playbook-NAME-OF-PROFILE.sh.Create a file
ansible_inventory.ymland include the following configuration snippet:all: hosts: localhost vars: ansible_connection: local
For SUSE Linux Enterprise products, run the following command:
>sudoansible-playbook -i ansible_inventory.yml NAME-OF-PRODUCT-playbook-NAME-OF-PROFILE.yml1Substitute NAME-OF-PRODUCT with
sle12orsle15. In addition, substitute NAME-OF-PROFILE with any of the supported profiles, as seen in the file names within the directory/usr/share/scap-security-guide/ansible/.To skip some of the rules during the execution, use the
--tagoption. You can find the tag of a specific rule by searching for the rule’s tag in the playbook file. For example, to skip some rules for SUSE Linux Enterprise 15, run the following command:>sudoansible-playbook -i ansible_inventory.yml sle15-playbook-NAME-OF-PROFILE.yml –tag “--tags "package_aide_installed,aide_build_database”For SUSE Linux Enterprise Micro, run the following commands:
>sudotransactional-update run ansible-playbook -i /root/ansible_inventory.yml smicro5-playbook-NAME-OF-PROFILE.yml>sudorebootTo skip some of the rules during the execution, use the
--tagoption. You can find the tag of a specific rule by searching for the rule’s tag in the playbook file. For example, to skip some rules for SUSE Linux Enterprise Micro, run the following command:>sudotransactional-update run ansible-playbook -i ansible_inventory.yml slmicro5-playbook-NAME-OF-PROFILE.yml –tag “--tags "package_aide_installed,aide_build_database”>sudorebootNoteFor SUSE Linux Enterprise Micro, you might need to repeat the steps more than twice, because of the following reasons:
Some of the rules require a restart of the system to take effect.
The rules are executed in an alphabetical order.
12 Legal Notice #
Copyright © 2006–2026 SUSE LLC and contributors. All rights reserved.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled “GNU Free Documentation License”.
For SUSE trademarks, see https://www.suse.com/company/legal/. All third-party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of SUSE and its affiliates. Asterisks (*) denote third-party trademarks.
All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.
13 GNU Free Documentation License #
Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
0. PREAMBLE #
The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or non-commercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
1. APPLICABILITY AND DEFINITIONS #
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
2. VERBATIM COPYING #
You may copy and distribute the Document in any medium, either commercially or non-commercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
3. COPYING IN QUANTITY #
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
4. MODIFICATIONS #
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
State on the Title page the name of the publisher of the Modified Version, as the publisher.
Preserve all the copyright notices of the Document.
Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
Include an unaltered copy of this License.
Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.
Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.
Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS #
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements".
6. COLLECTIONS OF DOCUMENTS #
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
7. AGGREGATION WITH INDEPENDENT WORKS #
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
8. TRANSLATION #
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
9. TERMINATION #
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
10. FUTURE REVISIONS OF THIS LICENSE #
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
ADDENDUM: How to use this License for your documents #
Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:
with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.