From 8c2b378cf1ee744ce1c891be60d6822c92e02c8e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C4=8Cern=C3=BD?= Date: Tue, 24 Jul 2018 10:26:52 +0200 Subject: [PATCH 1/4] Enable processing by both asciidoc and asciidoctor The asciidoc command does not support certain syntax that is supported by asciidoctor command. Fortunately, we can use syntax that is compatible with both programs. Most notable changes are: - Do not use triple backquotes for monospaced text, use single backquotes that work in both programs. - Use ---- for source code listing everywhere because they are rendered differently in asciidoc than indented blocks, whereas in asciidoctor they looked the same as indented blocks. - Use explicit wrapping in source code listing because asciidoc doesn't wrap long lines implicitly in source code listings, which causes ugly overlows and extremely long lines that are hard to read. - Fix SSG link. --- docs/contribute/testing.adoc | 2 - docs/developer/developer.adoc | 153 ++++++----- docs/manual/manual.adoc | 477 ++++++++++++++++++++++------------ 3 files changed, 398 insertions(+), 234 deletions(-) diff --git a/docs/contribute/testing.adoc b/docs/contribute/testing.adoc index f2ae734fb2..7f898190bf 100644 --- a/docs/contribute/testing.adoc +++ b/docs/contribute/testing.adoc @@ -33,7 +33,6 @@ to define your own scripts (usually written in Bash or Python) to extend XCCDF rule checking capabilities. Custom check scripts can be referenced from an XCCDF rule using `` element, for example: [[app-listing]] -[subs=+quotes] ---- @@ -275,7 +274,6 @@ link:../../tests/sce/CMakeLists.txt[tests/sce/CMakeLists.txt] and we will add our test script file using the `add_oscap_test` function which will make sure that our test will be executed by the `make test`: [[app-listing]] -[subs=+quotes] ---- if(ENABLE_SCE) ... diff --git a/docs/developer/developer.adoc b/docs/developer/developer.adoc index aeb3b8efab..c1829087f0 100644 --- a/docs/developer/developer.adoc +++ b/docs/developer/developer.adoc @@ -7,10 +7,9 @@ This part of documentation is meant to serve mainly to developers who want to contribute to OpenSCAP, help to fix bugs, or take an advantage of the OpenSCAP library and create own projects on top of it. -toc::[] == Building OpenSCAP on Linux -If you want to build the ```libopenscap``` library and the ```oscap``` tool from +If you want to build the `libopenscap` library and the `oscap` tool from the {oscap_git}[source code] then follow these instructions: . *Get the source code* @@ -18,18 +17,22 @@ the {oscap_git}[source code] then follow these instructions: Choose *1a* or *1b* depending on whether you want sources from a release tarball or the git repository. .. Use a release tarball: - - # replace ${version} with the desired version - wget https://github.com/OpenSCAP/openscap/releases/download/${version}/openscap-${version}.tar.gz - tar -xzpf openscap-${version}.tar.gz - cd openscap-${version} ++ +---- +# replace ${version} with the desired version +wget https://github.com/OpenSCAP/openscap/releases/download/${version}/openscap-${version}.tar.gz +tar -xzpf openscap-${version}.tar.gz +cd openscap-${version} +---- + **OR** .. Use fresh sources from git repository. - - $ git clone https://github.com/OpenSCAP/openscap.git - $ cd openscap ++ +---- +$ git clone https://github.com/OpenSCAP/openscap.git +$ cd openscap +---- + . *Get the build dependencies* @@ -37,7 +40,7 @@ Choose *1a* or *1b* depending on whether you want sources from a release tarball -- To build the library you will also need to install the build dependencies. -Build dependencies may vary depending on enabled features (by the ```cmake``` command). +Build dependencies may vary depending on enabled features (by the `cmake` command). Some of the dependencies are optional, if they are not detected, openscap will be compiled without respective optional features. @@ -65,11 +68,15 @@ When you have all the build dependencies installed you can build the library. . *Build the library* + +-- Run the following commands to build the library: - $ cd build/ - $ cmake ../ - $ make +---- +$ cd build/ +$ cmake ../ +$ make +---- +-- . *Build the HTML documentation* + @@ -100,36 +107,48 @@ subdirectories: . *Run the tests* + +-- After building the library you might want to run library self-checks. To do that you need to have these additional packages installed: - wget lua which procps-ng initscripts chkconfig sendmail -+ +---- +wget lua which procps-ng initscripts chkconfig sendmail +---- + and it is also required to have `sendmail` service running on the system: - $ systemctl start sendmail.service -+ +---- +$ systemctl start sendmail.service +---- + Now you can execute the following command to run library self-checks: - $ ctest -+ +---- +$ ctest +---- + It's also possible to use `ctest` to test any other oscap binary present in the system. You just have to set the path of the binary to the CUSTOM_OSCAP variable: - $ export CUSTOM_OSCAP=/usr/bin/oscap; ctest -+ -Not every check tests the oscap tool, however, when the CUSTOM_OSCAP variable is set, only the checks which do are executed. +---- +$ export CUSTOM_OSCAP=/usr/bin/oscap; ctest +---- +Not every check tests the oscap tool, however, when the CUSTOM_OSCAP variable is set, only the checks which do are executed. +-- . *Install* + +-- Run the installation procedure by executing the following command: - $ make install - +---- +$ make install +---- +-- == Running oscap -It is important to use your compiled ```libopenscap.so``` library with your ```oscap``` tool. -The easiest way how to achieve that without need to install ```libopenscap.so``` to the system path, is to use a shell script called *run* in the OpenSCAP build directory. +It is important to use your compiled `libopenscap.so` library with your `oscap` tool. +The easiest way how to achieve that without need to install `libopenscap.so` to the system path, is to use a shell script called *run* in the OpenSCAP build directory. ------------------------------------------------- $ cd build/ @@ -138,7 +157,7 @@ $ bash ./run utils/oscap xccdf eval ... whatever The *run* script is generated at configure time by CMake and it sets the following environment variables: -* *LD_LIBRARY_PATH* - path to ```libopenscap.so``` +* *LD_LIBRARY_PATH* - path to `libopenscap.so` * *OSCAP_SCHEMA_PATH* - path to XCCDF, OVAL, CPE, ... XSD schemas and schematrons (required for correct SCAP content validation) * *OSCAP_XSLT_PATH* - path to XSLT transformations. (required if you want @@ -153,17 +172,17 @@ or possible bugs in their security policies have these possibilities: The verbose mode provides user additional information about process of system scanning. The mode is useful for diagnostics of SCAP content evaluation and also for debugging. It produces a detailed report log with various messages. -The mode is available for ```xccdf eval```, ```oval eval```, ```oval collect``` -and ```oval analyse``` modules. +The mode is available for `xccdf eval`, `oval eval`, `oval collect` +and `oval analyse` modules. There is no need to special compilation, the feature is available for all OpenSCAP users. -To turn the verbose mode on, run ```oscap``` with this option: +To turn the verbose mode on, run `oscap` with this option: -* ```--verbose VERBOSITY_LEVEL``` - Turn on verbose mode at specified +* `--verbose VERBOSITY_LEVEL` - Turn on verbose mode at specified verbosity level. -The ```VERBOSITY_LEVEL``` can be one of: +The `VERBOSITY_LEVEL` can be one of: 1. *DEVEL* - the most detailed information for developers and bug hunters 2. *INFO* - reports content processing and system scanning @@ -172,7 +191,7 @@ The ```VERBOSITY_LEVEL``` can be one of: The verbose messages will be written on standard error output (stderr). Optionally, you can write the log into a file using - ```--verbose-log-file FILE```. + `--verbose-log-file FILE`. This is an example describing how to run OpenSCAP in verbose mode: @@ -196,7 +215,7 @@ $ cmake -DCMAKE_BUILD_TYPE=Debug .. && make Debug mode provides: -* debug symbols on and optimization off - you can use ```gdb```, +* debug symbols on and optimization off - you can use `gdb`, every process that was run. * http://www.gnu.org/software/gawk/manual/html_node/Assert-Function.html[assertions] are evaluated. @@ -204,15 +223,19 @@ are evaluated. ==== Example - $ bash ./run gdb --args utils/oscap xccdf eval --profile hard --results xccdf-results.xml --oval-results my-favourite-xccdf-checklist.xml +---- +$ bash ./run gdb --args utils/oscap xccdf eval \ +--profile hard --results xccdf-results.xml \ +--oval-results my-favourite-xccdf-checklist.xml +---- -The ```--oval-results``` option force ```oscap``` tool to generate OVAL Result file +The `--oval-results` option force `oscap` tool to generate OVAL Result file for each OVAL session used for evaluation. It's also very useful for debugging! === Environment variables -There are few more environment variables that control ```oscap``` tool +There are few more environment variables that control `oscap` tool behaviour. * *OSCAP_FULL_VALIDATION=1* - validate all exported documents (slower) @@ -226,34 +249,44 @@ We could separate the process into five phases. 1) *Get dependencies* - # dnf install lcov +---- +# dnf install lcov +---- 2) *Run CMake & make* To allow code to generate statistics, we need to compile it with specific flags. - $ CFLAGS="--coverage -ftest-coverage -fprofile-arcs" LDFLAGS=-lgcov cmake -DCMAKE_BUILD_TYPE=Debug ../ - $ make +---- +$ CFLAGS="--coverage -ftest-coverage -fprofile-arcs" LDFLAGS=-lgcov cmake -DCMAKE_BUILD_TYPE=Debug ../ +$ make +---- 3) *Run code* In this phase we should run code. We can run it directly or via test suite. - $ bash ./run utils/oscap +---- +$ bash ./run utils/oscap +---- 4) *Generate and browse results* - $ lcov -t "OpenSCAP coverage" -o ./coverage.info -c -d . - $ genhtml -o ./coverage ./coverage.info - $ xdg-open ./coverage/index.html # open results in browser +---- +$ lcov -t "OpenSCAP coverage" -o ./coverage.info -c -d . +$ genhtml -o ./coverage ./coverage.info +$ xdg-open ./coverage/index.html # open results in browser +---- 5) *Clean stats* Every run only modify our current statistics and not rewrite them completely. If we want to generate new statistics, we should remove the old ones. - $ lcov --directory ./ --zerocounters ; find ./ -name "*.gcno" | xargs rm - $ rm -rf ./coverage +---- +$ lcov --directory ./ --zerocounters ; find ./ -name "*.gcno" | xargs rm +$ rm -rf ./coverage +---- == Building OpenSCAP on Windows using Visual Studio @@ -299,14 +332,14 @@ cmake -D ENABLE_PYTHON3=FALSE -D CMAKE_TOOLCHAIN_FILE=c:/devel/vcpkg/scripts/bui 1. Launch Visual Studio 2. Click on File -> Open -> Project/Solution... -3. Locate ```c:\devel\openscap\build\openscap.sln``` +3. Locate `c:\devel\openscap\build\openscap.sln` 5) Build 1. Select build type (Debug, Release, ...) in the drop-down menu in the top panel. 2. Click on Build -> Build Solution. -Built binaries and their dependencies are now located in ```C:\devel\openscap\build\\```, eg. ```C:\devel\openscap\build\Debug\``` +Built binaries and their dependencies are now located in `C:\devel\openscap\build\\`, eg. `C:\devel\openscap\build\Debug\` == Building OpenSCAP for Windows on a Linux box (cross-compilation) Currently it is possible to cross-compile OpenSCAP for Windows only without probes. @@ -318,34 +351,34 @@ Instructions for cross-compiling OpenSCAP for Windows: NOTE: mingw32-pthreads needs to be version 5.0 or greater. ------------------------------------------------------------- - # yum install mingw32-gcc mingw32-binutils mingw32-libxml2 \ - mingw32-libgcrypt mingw32-pthreads mingw32-libxslt \ - mingw32-curl mingw32-pcre \ - mingw32-filesystem mingw32-bzip2 +# yum install mingw32-gcc mingw32-binutils mingw32-libxml2 \ +mingw32-libgcrypt mingw32-pthreads mingw32-libxslt \ +mingw32-curl mingw32-pcre \ +mingw32-filesystem mingw32-bzip2 ------------------------------------------------------------- 2) Checkout the master branch of the OpenSCAP repository ---------------------------------------------------------------------- - $ git clone -b master https://github.com/openscap/openscap.git - $ cd openscap +$ git clone -b master https://github.com/openscap/openscap.git +$ cd openscap ---------------------------------------------------------------------- 3) Prepare the build ---------------------------------------------------------------------------------- - $ mkdir build-win32 - $ cd build-win32 - $ mingw32-cmake -D ENABLE_PYTHON3=FALSE -D ENABLE_PROBES=FALSE -D ENABLE_OSCAP_UTIL_DOCKER=FALSE ../ +$ mkdir build-win32 +$ cd build-win32 +$ mingw32-cmake -D ENABLE_PYTHON3=FALSE -D ENABLE_PROBES=FALSE -D ENABLE_OSCAP_UTIL_DOCKER=FALSE ../ ---------------------------------------------------------------------------------- 4) Build! ------------------------------ - $ make +$ make ------------------------------ -Resulting ```oscap.exe``` can be found in the ```utils/``` directory. +Resulting `oscap.exe` can be found in the `utils/` directory. If you would like to send us a patch fixing any Windows diff --git a/docs/manual/manual.adoc b/docs/manual/manual.adoc index 3ef658b0b6..02cc73533c 100644 --- a/docs/manual/manual.adoc +++ b/docs/manual/manual.adoc @@ -34,26 +34,26 @@ toc::[] == Introduction This documentation provides information about a command-line tool called - ```oscap``` and its most common operations. With ```oscap``` you can check + `oscap` and its most common operations. With `oscap` you can check security configuration settings of a system, and examine the system for signs of a compromise by using rules based on standards and specifications. The - ```oscap``` uses {scap}[SCAP] which is a line of specifications maintained by + `oscap` uses {scap}[SCAP] which is a line of specifications maintained by the {nist}[NIST] which was created to provide a standardized approach for maintaining system security. New specifications are governed by NIST's SCAP http://scap.nist.gov/timeline.html[Release cycle] in order to provide a -consistent and repeatable revision workflow. The ```oscap``` mainly processes +consistent and repeatable revision workflow. The `oscap` mainly processes the {xccdf}[XCCDF] which is a standard way of expressing a checklist content and defines security checklists. It also combines with other specifications such as {cpe}[CPE], {cce}[CCE] and {oval}[OVAL] to create a SCAP-expressed checklist that can be processed by SCAP-validated products. For more information about the SCAP please refer to http://open-scap.org/features/standards/[SCAP Standards]. -The ```oscap``` tool is a part of the {openscap_web}[OpenSCAP] project. If you're +The `oscap` tool is a part of the {openscap_web}[OpenSCAP] project. If you're interested in a graphical alternative to this tool please visit {workbench_url}[SCAP Workbench] page. -We will use the _scap-security-guide_ {ssg}[SSG] project to provide us the SCAP +We will use the {ssg}[SCAP Security Guide] project to provide us the SCAP content. It provides security policies written in a form of SCAP documents covering many areas of computer security, and it implements security guidances recommended by respected authorities, namely {pci_dss}[PCI DSS], {stig}[STIG], and @@ -77,12 +77,12 @@ information about CPE applicability. If you want to perform configuration or vulnerability scans of a local system then the following must be available: - . A tool (```oscap``` or SCAP Workbench) + . A tool (`oscap` or SCAP Workbench) . SCAP content (XCCDF, OVAL...) === Installation -You can either build the OpenSCAP library and the ```oscap``` tool from +You can either build the OpenSCAP library and the `oscap` tool from {oscap_git}[source] (for details please refer to the <> section), or you can use an existing build for your Linux distribution. Use the following yum command if you want to install the oscap tool on your @@ -92,10 +92,10 @@ Fedora or Red Hat Enterprise Linux distribution: # yum install openscap-scanner ---------------------------- -NOTE: If the ```openscap-scanner``` is not available install - ```openscap-utils``` instead. +NOTE: If the `openscap-scanner` is not available install + `openscap-utils` instead. -Before you can start using the ```oscap``` tool you must have some SCAP content +Before you can start using the `oscap` tool you must have some SCAP content on your system. You can download it from the respective web site but we will use the SSG project in the following sections. You can build it from the {ssg_git}[source] or you can install it using a package management system: @@ -106,8 +106,8 @@ will use the SSG project in the following sections. You can build it from the The SCAP content will be installed in *__/usr/share/xml/scap/ssg/content/__*. -When the SCAP content is imported or installed on your system, ```oscap``` can -process the content by specifying the file path to the content. The ```oscap``` +When the SCAP content is imported or installed on your system, `oscap` can +process the content by specifying the file path to the content. The `oscap` supports SCAP {scap_1-2}[1.2] and is backward compatible with SCAP {scap_1-1}[1.1] and SCAP {scap_1-0}[1.0]. No special treatment is required in order to import and process earlier versions of the SCAP content. @@ -120,8 +120,8 @@ $ oscap -V ---------- === Displaying Information about SCAP Content -One of the capabilities of ```oscap``` is to display information about the SCAP -contents within a file. Running the ```oscap info``` command allows the +One of the capabilities of `oscap` is to display information about the SCAP +contents within a file. Running the `oscap info` command allows the examination of the internal structure of a SCAP document and displays information such as the document type, specification version, status, the date the document was published (**Generated**) and the date the document was copied to @@ -239,7 +239,8 @@ TestResult element. The **start-time** and **end-time** attributes contain the e times and dates. ---- - ---- To look up the dates in ARF file open the file and again look for the TestResult @@ -249,7 +250,9 @@ elements. The elements will be located in the arf:report elements. - ---- You can also find both dates in a HTML report, table **Evaluation @@ -257,7 +260,7 @@ characteristics**. To generate HTML report from XCCDF result or ARF, use `oscap xccdf generate report` command. === Scanning with OSCAP -The main goal of the ```oscap``` tool is to perform configuration and +The main goal of the `oscap` tool is to perform configuration and vulnerability scans of a local system. Oscap is able to evaluate both XCCDF benchmarks and OVAL definitions and generate the appropriate results. Please note that SCAP content can be provided either in a @@ -267,7 +270,7 @@ approaches. ==== OVAL The SCAP document can have a form of a single OVAL file (an OVAL -Definition file). The ```oscap``` tool processes the OVAL Definition file +Definition file). The `oscap` tool processes the OVAL Definition file during evaluation of OVAL definitions. It collects system information, evaluates it and generates an OVAL Result file. The result of evaluation of each OVAL definition is printed to standard output @@ -313,10 +316,15 @@ OVAL definitions evaluation. The following commands are examples of this scenario: ---- -$ oscap xccdf export-oval-variables --profile united_states_government_configuration_baseline usgcb-rhel5desktop-xccdf.xml +$ oscap xccdf export-oval-variables \ +--profile united_states_government_configuration_baseline \ +usgcb-rhel5desktop-xccdf.xml ---- ---- -$ oscap oval eval --variables usgcb-rhel5desktop-oval.xml-0.variables-0.xml --results usgcb-results-oval.xml usgcb-rhel5desktop-oval.xml +$ oscap oval eval \ +--variables usgcb-rhel5desktop-oval.xml-0.variables-0.xml \ +--results usgcb-results-oval.xml +usgcb-rhel5desktop-oval.xml ---- Where *united_states_government_configuration_baseline* represents a profile in the XCCDF document, *usgcb-rhel5desktop-xccdf.xml* is a file @@ -333,10 +341,19 @@ full results: ---- - + OpenSCAP - 5.8 + + 5.8 2017-02-04T00:00:00 @@ -426,7 +443,7 @@ you can also inspect XCCDF and OVAL content directly in Source DataStream or Result DataStream. ==== XCCDF -When evaluating an XCCDF benchmark, ```oscap``` usually processes an XCCDF +When evaluating an XCCDF benchmark, `oscap` usually processes an XCCDF file, an OVAL file and the CPE dictionary. It performs system analysis and produces XCCDF results based on this analysis. The results of the scan do not have to be saved in a separate file but can be @@ -460,7 +477,7 @@ Where *scap-xccdf.xml* is the XCCDF document, *Desktop* is the selected profile from the XCCDF document, *xccdf-results.xml* is a file storing the scan results, and *cpe-dictionary.xml* is the CPE dictionary. -* You can additionaly add ```--rule``` option to the above command to evaluate +* You can additionaly add `--rule` option to the above command to evaluate a specific rule: ---- @@ -472,7 +489,7 @@ profile which will be evaluated. ==== Source DataStream Commonly, all required input files are bundled together in Source DataStream. -Scanning using Source DataStream is also handled by ```oscap xccdf eval``` command, +Scanning using Source DataStream is also handled by `oscap xccdf eval` command, with some additional parameters available to determine which of the bundled benchmarks should be performed. @@ -488,8 +505,8 @@ collection, *ds.xml* is the particular DataStream, *xccdf.xml* is ID of the component-ref pointing to the desired XCCDF document, and *xccdf-results.xml* is a file containing the scan results. -NOTE: If you omit ```--datastream-id``` on the command line, the first data -stream from the collection will be used. If you omit ```--xccdf-id```, the +NOTE: If you omit `--datastream-id` on the command line, the first data +stream from the collection will be used. If you omit `--xccdf-id`, the first component from the checklists element will be used. If you omit both, the first DataStream that has a component in the checklists element will be used - the first component in its checklists element @@ -531,7 +548,7 @@ $ oscap xccdf eval --profile stig-rhel7-disa --stig-viewer results-stig.xml ssg- -------------------------------------------------------------------------------------- Each rule in the input XCCDF must contain a reference to its STIG Rule ID, and its -href attribute must be exactly "http://iase.disa.mil/stigs/Pages/stig-viewing-guidance.aspx". +href attribute must be exactly `http://iase.disa.mil/stigs/Pages/stig-viewing-guidance.aspx`. For example: ---- @@ -552,14 +569,14 @@ instructions. System remediation consists of the following steps: - . ```oscap``` performs a regular XCCDF evaluation. + . `oscap` performs a regular XCCDF evaluation. . An assessment of the results is performed by evaluating the OVAL definitions. Each rule that has failed is marked as a candidate for remediation. - . ```oscap``` searches for an appropriate fix element, resolves it, prepares the + . `oscap` searches for an appropriate fix element, resolves it, prepares the environment, and executes the fix script. - . Any output of the fix script is captured by ```oscap``` and stored within the + . Any output of the fix script is captured by `oscap` and stored within the *rule-result* element. The return value of the fix script is stored as well. - . Whenever ```oscap``` executes a fix script, it immediately evaluates the OVAL + . Whenever `oscap` executes a fix script, it immediately evaluates the OVAL definition again (to verify that the fix script has been applied correctly). During this second run, if the OVAL evaluation returns success, the result of the rule is *fixed*, otherwise it is an *error*. @@ -568,14 +585,14 @@ System remediation consists of the following steps: scan prior to the remediation. The second *TestResult* is derived from the first one and contains remediation results. -There are three modes of operation of ```oscap``` with regard to remediation: +There are three modes of operation of `oscap` with regard to remediation: online, offline, and review. ==== Online Remediation Online remediation executes fix elements at the time of scanning. Evaluation and remediation are performed as a part of a single command. -To enable online remediation, use the ```--remediate``` command-line option. For +To enable online remediation, use the `--remediate` command-line option. For example, to execute online remediation using the _scap-security-guide_ package, run: @@ -595,7 +612,7 @@ Offline remediation allows you to postpone fix execution. In first step, the system is only evaluated, and the results are stored in a *TestResult* element in an XCCDF file. -In the second step, ```oscap``` executes the fix scripts and verifies the result. It +In the second step, `oscap` executes the fix scripts and verifies the result. It is safe to store the results into the input file, no data will be lost. During offline remediation, a new *TestResult* element is created that is based on the input one and inherits all the data. The newly created *TestResult* @@ -616,8 +633,13 @@ The review mode allows users to store remediation instructions to a file for further review. The remediation content is not executed during this operation. To generate remediation instructions in the form of a shell script, run: - $ oscap xccdf generate fix --template urn:xccdf:fix:script:sh --profile xccdf_org.ssgproject.content_profile_rht-ccp --output my-remediation-script.sh /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml - +---- +$ oscap xccdf generate fix \ +--fix-type bash \ +--profile xccdf_org.ssgproject.content_profile_rht-ccp \ +--output my-remediation-script.sh \ +/usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml +---- === Check Engines Most XCCDF content uses the OVAL check engine. This is when OVAL @@ -696,13 +718,20 @@ metadata for other types of identifiers. Another place where these identifiers can be found are machine-readable Result Datastream files. This file can be generated during the scan by adding *--results-arf* option. - $ oscap xccdf eval --profile xccdf_org.ssgproject.content_profile_common --fetch-remote-resources --results-arf results.xml /usr/share/xml/scap/ssg/content/ssg-rhel6-ds.xml +---- +$ oscap xccdf eval \ +--profile xccdf_org.ssgproject.content_profile_common \ +--fetch-remote-resources --results-arf results.xml \ +/usr/share/xml/scap/ssg/content/ssg-rhel6-ds.xml +---- Result data stream file **results.xml** contains these identifiers in elements. ---- - + pass CCE-27173-4 @@ -752,14 +781,16 @@ WARNING: SCE is not part of any SCAP specification. === Validating SCAP Content Before you start using a security policy on your systems, you should first verify the policy in order to avoid any possible syntax or semantic errors in -the policy. The ```oscap``` tool can be used to validate the security content +the policy. The `oscap` tool can be used to validate the security content against standard SCAP XML schemas. The validation results are printed to the standard error stream (stderr). The general syntax of such a validation command is the following: - $ scap module validate [module_options_and_arguments] file +---- +$ oscap module validate [module_options_and_arguments] file +---- -where file is the full path to the file being validated. As a ```module``` you +where file is the full path to the file being validated. As a `module` you can use: * xccdf, @@ -770,7 +801,9 @@ can use: The only exception is the data stream module (ds), which uses the sds-validate operation instead of validate. So for example, it would be like: - $ oscap ds sds-validate scap-ds.xml +---- +$ oscap ds sds-validate scap-ds.xml +---- NOTE: Note that all SCAP components within the given data stream are validated automatically and none of the components is specified separately. @@ -779,18 +812,20 @@ You can also enable extra Schematron-based validation if you validate OVAL specification. This validation method is slower but it provides deeper analysis. Run the following command to validate an OVAL document using Schematron: - $ oscap oval validate --schematron oval-file.xml +---- +$ oscap oval validate --schematron oval-file.xml +---- The results of validation are printed to standard error stream (stderr). -NOTE: Please note that for the rest of ```oscap``` functionality, unless you specify +NOTE: Please note that for the rest of `oscap` functionality, unless you specify --skip-valid, validation will automatically occur before files are used. Therefore, you do not need to explicitly validate a datastream before use. === SCAP Content Signing and Signature Verification -The ```oscap``` itself does not do signature verification. It skips over the +The `oscap` itself does not do signature verification. It skips over the respective elements. This is due to the fact that there are way too many options when it comes to keystores and crypto choices. Instead we recommend users to use {xmlsec}[xmlsec1] to verify their SCAP content. Safely evaluating signed @@ -801,7 +836,7 @@ content (with signature verification) involves the following steps: # yum install xmlsec1 xmlsec1-openssl ------------------------------------- -2) Run ```xmlsec1 --verify``` on the content: +2) Run `xmlsec1 --verify` on the content: This simple example will only show 2 specific cases of verifying the signature, the steps may vary depending on which technique was used to @@ -821,8 +856,8 @@ respective public part of the certificate to verify it with: $ xmlsec1 --verify --pubkey-cert-pem pubcert.key datastream.xml --------------------------------------------------------------- -There are countless other options, for more details see: ```xmlsec1 ---help-verify``` +There are countless other options, for more details see: `xmlsec1 +--help-verify` Successful output should look similar to this: @@ -843,11 +878,11 @@ $ oscap xccdf eval datastream.xml --------------------------------- NOTE: If you want to experiment with various crypto engines of xmlsec1, see - ```xmlsec1-config --help``` + `xmlsec1-config --help` === Generating Reports and Guides -Another useful features of ```oscap``` is the ability to generate SCAP content in a +Another useful features of `oscap` is the ability to generate SCAP content in a human-readable format. It allows you to transform an XML file into HTML or plain-text format. This feature is used to generate security guides and checklists, which serve as a source of information, as well as @@ -855,12 +890,14 @@ guidance for secure system configuration. The results of system scans can also be transformed to well-readable result reports. The general command syntax is the following: - $ oscap module generate sub-module [specific_module/sub-module_options_and_arguments] file +---- +oscap module generate sub-module [specific_module/sub-module_options_and_arguments] file +---- -where module is either ```xccdf``` or ```oval```, ```sub-module``` is a type of +where module is either `xccdf` or `oval`, `sub-module` is a type of the generated document, and file represents an XCCDF or OVAL file. A sub-module -can be either ```report```, ```guide```, ```custom``` or ```fix```. Please see - ```man oscap``` for more details. +can be either `report`, `guide`, `custom` or `fix`. Please see + `man oscap` for more details. === Content Transformation @@ -899,7 +936,8 @@ $ oscap oval generate report oval-results.xml > report-oval.html OVAL tests (see an https://static.open-scap.org/examples/report-xccdf-oval.html[example]): ---- -$ oscap xccdf generate report --oval-template oval-results.xml xccdf-results.xml > report-xccdf-oval.html +$ oscap xccdf generate report \ +--oval-template oval-results.xml xccdf-results.xml > report-xccdf-oval.html ---- @@ -917,7 +955,7 @@ If an XCCDF rule contains no ** elements it is considered always applicable. If the CPE name or CPE2 platform is defined in an external file, use the - ```--cpe``` option and ```oscap``` auto-detects format of the file. The following + `--cpe` option and `oscap` auto-detects format of the file. The following command is an example of the XCCDF content evaluation using CPE name from an external file: @@ -929,7 +967,7 @@ Where *xccdf-file.xml* is the XCCDF document, *xccdf-results.xml* is a file containing the scan results, and *external-cpe-file.xml* is the CPE dictionary or a language file. -If you are evaluating a source data stream, ```oscap``` automatically +If you are evaluating a source data stream, `oscap` automatically registers all CPEs contained within the data stream. No extra steps have to be taken. You can also register an additional external CPE file, as shown by the command below: @@ -944,7 +982,7 @@ XCCDF document, *xccdf-results.xml* is a file containing the scan results, and *additional-external-cpe.xml* is the additional CPE dictionary or language file. -The ```oscap``` tool will use an OVAL file attached to the CPE dictionary to +The `oscap` tool will use an OVAL file attached to the CPE dictionary to determine applicability of any CPE name in the dictionary. Apart from the instructions above, no extra steps have to be taken for @@ -980,7 +1018,7 @@ deem it applicable ==== Built-in CPE Naming Dictionary -Apart from the external CPE Dictionaries, ```oscap``` comes with an inbuilt +Apart from the external CPE Dictionaries, `oscap` comes with an inbuilt CPE Dictionary. The built-in CPE Dictionary contains only a few products (sub-set of http://nvd.nist.gov/cpe.cfm[Official CPE Dictionary]) and it is used as a fall-back option when there is no other CPE source found. @@ -999,7 +1037,7 @@ https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora[bugzilla]. === Notes on the Concept of Multiple OVAL Values This section describes advanced concepts of OVAL Variables and their -implementation in ```oscap```. The SCAP specification allows for an OVAL +implementation in `oscap`. The SCAP specification allows for an OVAL variable to have multiple values during a single assessment run. There are two variable modes which can be combined: @@ -1027,7 +1065,7 @@ hand, the second concept is not supported by an OVAL Variable schema which prevents fully automated evaluation of the multisets (unless you use XCCDF to bridge that gap). -TIP: ```oscap``` supports both variable modes as described below. +TIP: `oscap` supports both variable modes as described below. ==== Sources of Variable Values First we need to understand how a single value can be bound to a @@ -1037,9 +1075,12 @@ variable in the OVAL checking engine. There are three ways to do this: defined in an external file. Such a file is called an OVAL Variable File and can be recognized by using the following command: `oscap info file.xml`. The OVAL Variables file can be passed to the evaluation by - ```--variables``` argument such as: + `--variables` argument such as: ---- -$ oscap oval eval --variables usgcb-rhel5desktop-oval.xml-0.variables-0.xml --results usgcb-results-oval.xml usgcb-rhel5desktop-oval.xml +$ oscap oval eval \ +--variables usgcb-rhel5desktop-oval.xml-0.variables-0.xml \ +--results usgcb-results-oval.xml \ +usgcb-rhel5desktop-oval.xml ---- 2) XCCDF Bindings -- The values of external variables can be given from @@ -1057,11 +1098,11 @@ directly in the OVAL definitions file ** and ** elements. ==== Evaluation of Multiple OVAL Values -With ```oscap```, there are two possible ways how two or more values can be +With `oscap`, there are two possible ways how two or more values can be specified for a variable used by one OVAL definition. The approach you choose depends on what mode you want to use, multival or multiset. -The ```oscap``` handles multiple OVAL values seemlessly; such that user doesn't +The `oscap` handles multiple OVAL values seemlessly; such that user doesn't need to do anything differently than what she (or he) does for a normal scan. The command below demonstrates evaluation of DataStream, which may include multiset, multival, or both concepts combined, or none of them. @@ -1079,21 +1120,23 @@ format (XSD schema) allows for multiple ** elements within each ** element. -------------------------------------------------------------------------------- - - 600 - 400 - + + 600 + 400 + -------------------------------------------------------------------------------- 2) XCCDF Bindings -- Use multiple ** referring to the very same OVAL variable binding with multiple different XCCDF values. ------------------------------------------------------------------------------------------------------ - - - - - ------------------------------------------------------------------------------------------------------ +---- + + + + + +---- 3) Values within OVAL Definitions file -- This is similar to using a Variables file, there are multiple ** elements allowed within @@ -1107,18 +1150,18 @@ Bindings. The following XCCDF snippet evaluates twice the very same OVAL Definition, each time it binds a different value to the OVAL variable. ------------------------------------------------------------------------------------------------------- - - - - - - - - - - - - + + + + + + + + + + + + ------------------------------------------------------------------------------------------------------- After the evaluation, the OVAL results file will contain multiple @@ -1130,16 +1173,18 @@ The following snippet of OVAL results file illustrates output of a multiset evaluation. ---- - - - - 600 - - - - 400 - - + + + + 600 + + + + 400 + + ---- @@ -1153,47 +1198,59 @@ other purposes. When you are evaluating SCAP content with external resources the `oscap` tool will warn you: - $ oscap xccdf eval --profile xccdf_org.ssgproject.content_profile_common /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml - WARNING: This content points out to the remote resources. Use `--fetch-remote-resources' option to download them. - WARNING: Skipping https://www.redhat.com/security/data/oval/com.redhat.rhsa-RHEL7.xml.bz2 file which is referenced from XCCDF content +---- +$ oscap xccdf eval \ +--profile xccdf_org.ssgproject.content_profile_common \ +/usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml + +WARNING: This content points out to the remote resources. Use `--fetch-remote-resources' option to download them. +WARNING: Skipping https://www.redhat.com/security/data/oval/com.redhat.rhsa-RHEL7.xml.bz2 file which is referenced from XCCDF content +---- By default the `oscap` tool will not blindly download and execute remote content. If you trust your local content and the remote content it references, you can use the `--fetch-remote-resources` option to automatically download it using the `oscap` tool. - $ oscap xccdf eval --fetch-remote-resources --profile xccdf_org.ssgproject.content_profile_common /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml - Downloading: https://www.redhat.com/security/data/oval/com.redhat.rhsa-RHEL7.xml.bz2 ... ok - Title Ensure /var/log Located On Separate Partition - Rule xccdf_org.ssgproject.content_rule_partition_for_var_log - ... +---- +$ oscap xccdf eval \ +--fetch-remote-resources \ +--profile xccdf_org.ssgproject.content_profile_common \ +/usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml +Downloading: https://www.redhat.com/security/data/oval/com.redhat.rhsa-RHEL7.xml.bz2 ... ok +Title Ensure /var/log Located On Separate Partition +Rule xccdf_org.ssgproject.content_rule_partition_for_var_log +... +---- === Evaluating XCCDF rules with multiple checks Normally, each XCCDF rule references to a single check with a specified name. -However, if ```@name``` attribute of ```xccdf:check-content-ref``` of a given rule is omitted, +However, if `@name` attribute of `xccdf:check-content-ref` of a given rule is omitted, multiple checks can be executed to evaluate the rule. -This is common for ```security_patches_up_to_date``` check. +This is common for `security_patches_up_to_date` check. By default, only a single result is produced for an XCCDF rule in such case, and the result is computed from all results of checks in the referenced location. -In case user wants to see separate results for each check (one ```xccdf:check-result``` element -in results document for each check evaluated), then ```multi-check``` attribute -of ```xccdf:check``` element must be set to *true*. - ----- - - Security Patches Up-To-Date - All known security patches have been installed. - - - - - - +In case user wants to see separate results for each check (one `xccdf:check-result` element +in results document for each check evaluated), then `multi-check` attribute +of `xccdf:check` element must be set to *true*. + +---- + + Security Patches Up-To-Date + All known security patches have been installed. + + + + + + ---- -In XCCDF specification older than 1.2, the ```multi-check``` element is not defined, +In XCCDF specification older than 1.2, the `multi-check` element is not defined, which means that only a single result is always produced. To produce separate results for each check from the content older than XCCDF version 1.2, you need to convert it first into XCCDF 1.2 using the following command: @@ -1202,7 +1259,7 @@ you need to convert it first into XCCDF 1.2 using the following command: $ xsltproc --stringparam reverse_DNS com.example.www /usr/share/openscap/xsl/xccdf_1.1_to_1.2.xsl xccdf.xml > xccdf-1.2.xml ---- -And then patch the content using a text editor, adding ```multi-check``` as +And then patch the content using a text editor, adding `multi-check` as shown in the example Rule snippet above. To create a source DataStream from the patched content, the following command can be used: @@ -1219,7 +1276,7 @@ To add a CPE dictionary component into your DataStream in place, use this comman $ oscap ds sds-add cpe_dictionary.xml source_ds.xml ---- -Now the ```source_ds.xml``` DataStream can be evaluated as usual. +Now the `source_ds.xml` DataStream can be evaluated as usual. == Practical Examples This section demonstrates practical usage of certain security content provided @@ -1233,22 +1290,30 @@ The SSG project contains guidance for settings of Red Hat Enterprise Linux 7. 1) Install the SSG - $ sudo yum install -y scap-security-guide +---- +$ sudo yum install -y scap-security-guide +---- -2) To inspect the security content use the ```oscap info``` module: +2) To inspect the security content use the `oscap info` module: - $ oscap info /usr/share/xml/scap/ssg/rhel7/ssg-rhel7-ds.xml +---- +$ oscap info /usr/share/xml/scap/ssg/rhel7/ssg-rhel7-ds.xml +---- The output of this command contains available configuration profiles. To audit your system settings choose the - ```xccdf_org.ssgproject.content_profile_rht-ccp``` profile and run the + `xccdf_org.ssgproject.content_profile_rht-ccp` profile and run the evaluation command . For example, the The following command is used to assess the given system against a draft SCAP profile for Red Hat Certified Cloud Providers: - $ oscap xccdf eval --profile xccdf_org.ssgproject.content_profile_rht-ccp ---results ssg-rhel7-xccdf-result.xml --report ssg-rhel7-report.html +---- +$ oscap xccdf eval \ +--profile xccdf_org.ssgproject.content_profile_rht-ccp \ +--results ssg-rhel7-xccdf-result.xml \ +--report ssg-rhel7-report.html \ /usr/share/xml/scap/ssg/rhel7/ssg-rhel7-ds.xml +---- === Auditing Security Vulnerabilities of Red Hat Products @@ -1326,11 +1391,13 @@ The Source DataStream use-case is very similar to OVAL+XCCDF. The only difference is that you don't have to download two separate files. 1) Download the content + --------------------------------------------------------------------------------- $ wget https://www.redhat.com/security/data/metrics/ds/com.redhat.rhsa-all.ds.xml --------------------------------------------------------------------------------- 2) Run the scan + -------------------------------------------------------------------------------------------- $ oscap xccdf eval --results results.xml --report report.html com.redhat.rhsa-all.ds.xml -------------------------------------------------------------------------------------------- @@ -1372,19 +1439,30 @@ Standard (PCI-DSS) on Red Hat Enterprise Linux 7. 1) Install SSG which provides the PCI-DSS SCAP content - $ sudo yum install -y scap-security-guide +---- +$ sudo yum install -y scap-security-guide +---- 2) Verify that the PCI-DSS profile is present - $ oscap info /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml +---- +$ oscap info /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml +---- 3) Evaluate the PCI-DSS content - $ oscap xccdf eval --results results.xml --profile xccdf_org.ssgproject.content_profile_pci-dss /usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml +---- +$ oscap xccdf eval \ +--results results.xml \ +--profile xccdf_org.ssgproject.content_profile_pci-dss \ +/usr/share/xml/scap/ssg/content/ssg-rhel7-ds.xml +---- 4) Generate report readable in a web browser. - $ oscap xccdf generate report --output report.html results.xml +---- +$ oscap xccdf generate report --output report.html results.xml +---- === How to Evaluate DISA STIG This section describes how to evaluate the Defense Information Systems Agency @@ -1407,20 +1485,25 @@ $ sed -i 's/ Date: Tue, 24 Jul 2018 11:53:48 +0200 Subject: [PATCH 2/4] Change CMakeLists to be able to use asciidoc Asciidoc could be used instead of asciidoctor. Changed the command line to be compatible with both programs. Explicitely set the HTML5 backend because it is not default in asciidoc. We have to make the target directory before we call the program, because asciidoc doesn't create directories automatically. If both asciidoc and asciidoctor are found, asciidoc is preferred. --- CMakeLists.txt | 2 +- docs/CMakeLists.txt | 13 ++++++++----- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 8c65b99e4a..a1a74d26c6 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -166,7 +166,7 @@ endif() mark_as_advanced(ENV_PRESENT VALGRIND_PRESENT) find_program(ENV_PRESENT env) find_program(VALGRIND_PRESENT valgrind) -find_program(ASCIIDOCTOR_EXECUTABLE asciidoctor) +find_program(ASCIIDOCTOR_EXECUTABLE NAMES asciidoc asciidoctor) find_program(SED_EXECUTABLE sed) find_program(GIT_EXECUTABLE git) diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 3de717830c..94979c7eac 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -23,7 +23,8 @@ endif() if(ASCIIDOCTOR_EXECUTABLE) add_custom_target(user_manual - COMMAND "${ASCIIDOCTOR_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/manual/manual.adoc" -o "${CMAKE_CURRENT_BINARY_DIR}/manual/manual.html" + COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/manual" + COMMAND "${ASCIIDOCTOR_EXECUTABLE}" -b html5 -o "${CMAKE_CURRENT_BINARY_DIR}/manual/manual.html" "${CMAKE_CURRENT_SOURCE_DIR}/manual/manual.adoc" COMMAND ${CMAKE_COMMAND} -E copy_directory "${CMAKE_CURRENT_SOURCE_DIR}/manual/images" "${CMAKE_CURRENT_BINARY_DIR}/manual/images" COMMENT "Generating OpenSCAP User Manual in HTML format" ) @@ -31,15 +32,17 @@ if(ASCIIDOCTOR_EXECUTABLE) DESTINATION "${CMAKE_INSTALL_DOCDIR}" ) add_custom_target(developer_manual - COMMAND "${ASCIIDOCTOR_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/developer/developer.adoc" -o "${CMAKE_CURRENT_BINARY_DIR}/developer/developer.html" + COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/developer" + COMMAND "${ASCIIDOCTOR_EXECUTABLE}" -b html5 -o "${CMAKE_CURRENT_BINARY_DIR}/developer/developer.html" "${CMAKE_CURRENT_SOURCE_DIR}/developer/developer.adoc" COMMENT "Generating OpenSCAP Developer Manual in HTML format" ) # We are not installing the OpenSCAP Developer manual because it does not # make any sense to install this for end-users. add_custom_target(contribute_docs - COMMAND "${ASCIIDOCTOR_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/contribute/contribute.adoc" -o "${CMAKE_CURRENT_BINARY_DIR}/contribute/contribute.html" - COMMAND "${ASCIIDOCTOR_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/contribute/testing.adoc" -o "${CMAKE_CURRENT_BINARY_DIR}/contribute/testing.html" - COMMAND "${ASCIIDOCTOR_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/contribute/versioning.adoc" -o "${CMAKE_CURRENT_BINARY_DIR}/contribute/versioning.html" + COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/contribute" + COMMAND "${ASCIIDOCTOR_EXECUTABLE}" -b html5 -o "${CMAKE_CURRENT_BINARY_DIR}/contribute/contribute.html" "${CMAKE_CURRENT_SOURCE_DIR}/contribute/contribute.adoc" + COMMAND "${ASCIIDOCTOR_EXECUTABLE}" -b html5 -o "${CMAKE_CURRENT_BINARY_DIR}/contribute/testing.html" "${CMAKE_CURRENT_SOURCE_DIR}/contribute/testing.adoc" + COMMAND "${ASCIIDOCTOR_EXECUTABLE}" -b html5 -o "${CMAKE_CURRENT_BINARY_DIR}/contribute/versioning.html" "${CMAKE_CURRENT_SOURCE_DIR}/contribute/versioning.adoc" COMMENT "Generating contribute documentation in HTML format" ) # We are not installing the contribute documentation because it does not From c66b0e1da0b1f62534e6665711beff1bac879a76 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C4=8Cern=C3=BD?= Date: Tue, 24 Jul 2018 12:00:53 +0200 Subject: [PATCH 3/4] Mention both AsciiDoc and AsciiDoctor in Developer Manual --- docs/developer/developer.adoc | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/developer/developer.adoc b/docs/developer/developer.adoc index c1829087f0..a37025e628 100644 --- a/docs/developer/developer.adoc +++ b/docs/developer/developer.adoc @@ -85,11 +85,14 @@ It is possible to generate a complete API documentation, User manual, Developer manual and contribute documents in HTML format. If you want to build the HTML documentation you will need to install Doxygen -and Asciidoctor. +and AsciiDoc. +To install AsciiDoc, you can run `dnf install asciidoc`. +To install Doxygen, you can run `dnf install doxygen`. + +To get a modern output look, you can use Asciidoctor instead of AsciiDoc. To install `asciidoctor`, you can either install `rubygem-asciidoctor` package (available on Fedora), or you can install `rubygems` package and then run `gem install asciidoctor`. -To install Doxygen, you can run `dnf install doxygen`. Run the following command to build the documentation: From 66e14d18d247ed6752e23ff54d5e69ed4d4053ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C4=8Cern=C3=BD?= Date: Wed, 25 Jul 2018 18:02:05 +0200 Subject: [PATCH 4/4] Use only asciidoc This will remove the possiblity of using asciidoctor in `make docs` build target. We will support only asciidoc, beacuse that command is available in many Linux distributions. Removed also a mention of asciidoctor from the Developer Manual. --- CMakeLists.txt | 2 +- docs/CMakeLists.txt | 12 ++++++------ docs/developer/developer.adoc | 5 ----- 3 files changed, 7 insertions(+), 12 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index a1a74d26c6..f10825689b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -166,7 +166,7 @@ endif() mark_as_advanced(ENV_PRESENT VALGRIND_PRESENT) find_program(ENV_PRESENT env) find_program(VALGRIND_PRESENT valgrind) -find_program(ASCIIDOCTOR_EXECUTABLE NAMES asciidoc asciidoctor) +find_program(ASCIIDOC_EXECUTABLE asciidoc) find_program(SED_EXECUTABLE sed) find_program(GIT_EXECUTABLE git) diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 94979c7eac..890192db07 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -21,10 +21,10 @@ if(DOXYGEN_FOUND) ) endif() -if(ASCIIDOCTOR_EXECUTABLE) +if(ASCIIDOC_EXECUTABLE) add_custom_target(user_manual COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/manual" - COMMAND "${ASCIIDOCTOR_EXECUTABLE}" -b html5 -o "${CMAKE_CURRENT_BINARY_DIR}/manual/manual.html" "${CMAKE_CURRENT_SOURCE_DIR}/manual/manual.adoc" + COMMAND "${ASCIIDOC_EXECUTABLE}" -b html5 -o "${CMAKE_CURRENT_BINARY_DIR}/manual/manual.html" "${CMAKE_CURRENT_SOURCE_DIR}/manual/manual.adoc" COMMAND ${CMAKE_COMMAND} -E copy_directory "${CMAKE_CURRENT_SOURCE_DIR}/manual/images" "${CMAKE_CURRENT_BINARY_DIR}/manual/images" COMMENT "Generating OpenSCAP User Manual in HTML format" ) @@ -33,16 +33,16 @@ if(ASCIIDOCTOR_EXECUTABLE) ) add_custom_target(developer_manual COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/developer" - COMMAND "${ASCIIDOCTOR_EXECUTABLE}" -b html5 -o "${CMAKE_CURRENT_BINARY_DIR}/developer/developer.html" "${CMAKE_CURRENT_SOURCE_DIR}/developer/developer.adoc" + COMMAND "${ASCIIDOC_EXECUTABLE}" -b html5 -o "${CMAKE_CURRENT_BINARY_DIR}/developer/developer.html" "${CMAKE_CURRENT_SOURCE_DIR}/developer/developer.adoc" COMMENT "Generating OpenSCAP Developer Manual in HTML format" ) # We are not installing the OpenSCAP Developer manual because it does not # make any sense to install this for end-users. add_custom_target(contribute_docs COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/contribute" - COMMAND "${ASCIIDOCTOR_EXECUTABLE}" -b html5 -o "${CMAKE_CURRENT_BINARY_DIR}/contribute/contribute.html" "${CMAKE_CURRENT_SOURCE_DIR}/contribute/contribute.adoc" - COMMAND "${ASCIIDOCTOR_EXECUTABLE}" -b html5 -o "${CMAKE_CURRENT_BINARY_DIR}/contribute/testing.html" "${CMAKE_CURRENT_SOURCE_DIR}/contribute/testing.adoc" - COMMAND "${ASCIIDOCTOR_EXECUTABLE}" -b html5 -o "${CMAKE_CURRENT_BINARY_DIR}/contribute/versioning.html" "${CMAKE_CURRENT_SOURCE_DIR}/contribute/versioning.adoc" + COMMAND "${ASCIIDOC_EXECUTABLE}" -b html5 -o "${CMAKE_CURRENT_BINARY_DIR}/contribute/contribute.html" "${CMAKE_CURRENT_SOURCE_DIR}/contribute/contribute.adoc" + COMMAND "${ASCIIDOC_EXECUTABLE}" -b html5 -o "${CMAKE_CURRENT_BINARY_DIR}/contribute/testing.html" "${CMAKE_CURRENT_SOURCE_DIR}/contribute/testing.adoc" + COMMAND "${ASCIIDOC_EXECUTABLE}" -b html5 -o "${CMAKE_CURRENT_BINARY_DIR}/contribute/versioning.html" "${CMAKE_CURRENT_SOURCE_DIR}/contribute/versioning.adoc" COMMENT "Generating contribute documentation in HTML format" ) # We are not installing the contribute documentation because it does not diff --git a/docs/developer/developer.adoc b/docs/developer/developer.adoc index a37025e628..388fd23a58 100644 --- a/docs/developer/developer.adoc +++ b/docs/developer/developer.adoc @@ -89,11 +89,6 @@ and AsciiDoc. To install AsciiDoc, you can run `dnf install asciidoc`. To install Doxygen, you can run `dnf install doxygen`. -To get a modern output look, you can use Asciidoctor instead of AsciiDoc. -To install `asciidoctor`, you can either install `rubygem-asciidoctor` package -(available on Fedora), or you can install `rubygems` package and then run -`gem install asciidoctor`. - Run the following command to build the documentation: ----