Clarify the '--local-files' option

- Document that the '--local-files' option works only with SCAP 1.3
  source data streams.
- Add a warning if users use '--local-files' with different versions of
  SCAP source data streams.
- Add a simple upstream test for the added warning.

Resolves: https://issues.redhat.com/browse/RHEL-74343

Author: jan-cerny

docs/manual/manual.adoc

@@ -1655,11 +1655,13 @@ Also, OpenSCAP uses `libcurl` library which also can be configured using environ
 
 == Using external or remote resources
 
-Some SCAP content references external resources. For example SCAP Security Guide
-uses external OVAL file to check that the system is up to date and has no known
+Some SCAP content references external resources. For example, older versions of SCAP Security Guide (prior to version 0.1.73)
+used external OVAL file to check that the system is up to date and has no known
 security vulnerabilities. However, other content can use external resources for
 other purposes.
 
+NOTE: Starting with version 0.1.73, SCAP Security Guide content doesn't use external resources anymore.
+
 When you are evaluating SCAP content with external resources the `oscap` tool
 will warn you:
 
@@ -1708,6 +1710,8 @@ $ wget -O ~/scap-files/security-data-oval-com.redhat.rhsa-RHEL8.xml https://www.
 $ oscap xccdf eval --local-files ~/scap-files --profile ospp ssg-rhel8-ds.xml
 ----
 
+NOTE: The `--local-files` option works only with SCAP 1.3 source data streams. It can't be used with SCAP 1.2 source data streams.
+
 == Practical Examples
 This section demonstrates practical usage of certain security content provided
 for Red Hat products.
@@ -2297,4 +2301,5 @@ You can find the ID of the customized profile with `oscap info <your_tailoring_f
 
 Yes, it's possible, you can download the file on other computer that is connected to the internet and then copy the file to the system where you run `oscap`.
 Instead of the `--fetch-remote-resources` option you will use the `--local-files` option.
+This option works only with SCAP 1.3 source data streams. It can't be used with SCAP 1.2 source data streams.
 For more information, please refer to section <<_using_external_or_remote_resources,Using external or remote resources>>.

src/DS/ds_sds_session.c

@@ -343,6 +343,25 @@ void ds_sds_session_configure_remote_resources(struct ds_sds_session *session, b
 	session->fetch_remote_resources = allowed;
 	session->local_files = local_files;
 	session->progress = (callback != NULL) ? callback : download_progress_empty_calllback;
+	if (local_files != NULL) {
+		struct ds_sds_index *idx = ds_sds_session_get_sds_idx(session);
+		struct ds_stream_index_iterator *streams = ds_sds_index_get_streams(idx);
+		while (ds_stream_index_iterator_has_more(streams)) {
+			struct ds_stream_index *stream = ds_stream_index_iterator_next(streams);
+			const char *version = ds_stream_index_get_version(stream);
+			if (strcmp(version, "1.3")) {
+				ds_sds_session_remote_resources_progress(session)(
+					true,
+					"WARNING: The '--local-files' option can be used only with "
+					"SCAP 1.3 source data streams, but the provided data stream "
+					"is version '%s'. No local files will be used.\n",
+					version);
+				break;
+			}
+
+		}
+		ds_stream_index_iterator_free(streams);
+	}
 }
 
 void ds_sds_session_set_remote_resources(struct ds_sds_session *session, bool allowed, download_progress_calllback_t callback)

tests/DS/test_ds_use_local_remote_resources.sh

@@ -4,7 +4,6 @@
 #   Jan Černý <jcerny@redhat.com>
 
 set -e -o pipefail
-set -x
 
 . $builddir/tests/test_common.sh
 
@@ -81,3 +80,13 @@ assert_exists 1 '//rule-result[@idref="xccdf_com.example.www_rule_test-pass2"]/r
 popd
 rm -f "$result" "$stderr"
 rm -rf "$tmpdir1" "$tmpdir2" "$tmpdir3"
+
+
+# test that a warning is shown when --local-files is provided with SCAP 1.2 DS
+result=$(mktemp)
+stderr=$(mktemp)
+tmpdir=$(mktemp -d)
+$OSCAP xccdf eval --local-files "$tmpdir" --profile "$PROFILE" --results "$result" "${srcdir}/ds_continue_without_remote_resources/remote_content_1.2.ds.xml" 2>"$stderr" || ret=$?
+[ "$ret" = 2 ]
+grep -q "WARNING: The '--local-files' option can be used only with SCAP 1.3 source data streams, but the provided data stream is version '1.2'. No local files will be used." "$stderr"
+rm -rf "$result" "$stderr" "$tmpdir"

utils/oscap.8

@@ -75,6 +75,7 @@ Allow download of remote components referenced from data stream.
 \fB\-\-local-files DIRECTORY\fR
 .RS
 Instead of downloading remote data stream components from the network, use data stream components stored locally as files in the given directory. In place of the remote data stream component OpenSCAP will attempt to use a file whose file name is equal to @name attribute of the uri element within the catalog element within the component-ref element in the data stream if such file exists.
+This option works only with SCAP 1.3 source data streams. It can't be used with SCAP 1.2 source data streams.
 .RE
 .TP
 \fB\-\-profile PROFILE\fR
@@ -225,6 +226,7 @@ Allow download of remote OVAL content referenced from XCCDF by check-content-ref
 \fB\-\-local-files DIRECTORY\fR
 .RS
 Instead of downloading remote data stream components from the network, use data stream components stored locally as files in the given directory. In place of the remote data stream component OpenSCAP will attempt to use a file whose file name is equal to @name attribute of the uri element within the catalog element within the component-ref element in the data stream if such file exists.
+This option works only with SCAP 1.3 source data streams. It can't be used with SCAP 1.2 source data streams.
 .RE
 .TP
 \fB\-\-remediate\fR
@@ -255,6 +257,7 @@ Allow download of remote OVAL content referenced from XCCDF by check-content-ref
 \fB\-\-local-files DIRECTORY\fR
 .RS
 Instead of downloading remote data stream components from the network, use data stream components stored locally as files in the given directory. In place of the remote data stream component OpenSCAP will attempt to use a file whose file name is equal to @name attribute of the uri element within the catalog element within the component-ref element in the data stream if such file exists.
+This option works only with SCAP 1.3 source data streams. It can't be used with SCAP 1.2 source data streams.
 .RE
 .TP
 \fB\-\-cpe CPE_FILE\fR
@@ -342,6 +345,7 @@ Allow download of remote OVAL content referenced from XCCDF by check-content-ref
 \fB\-\-local-files DIRECTORY\fR
 .RS
 Instead of downloading remote data stream components from the network, use data stream components stored locally as files in the given directory. In place of the remote data stream component OpenSCAP will attempt to use a file whose file name is equal to @name attribute of the uri element within the catalog element within the component-ref element in the data stream if such file exists.
+This option works only with SCAP 1.3 source data streams. It can't be used with SCAP 1.2 source data streams.
 .RE
 .TP
 \fB\-\-skip-valid\fR, \fB\-\-skip-validation\fR
@@ -518,6 +522,7 @@ Allow download of remote components referenced from data stream.
 .TP
 \fB\-\-local-files DIRECTORY\fR
 Instead of downloading remote data stream components from the network, use data stream components stored locally as files in the given directory. In place of the remote data stream component OpenSCAP will attempt to use a file whose file name is equal to @name attribute of the uri element within the catalog element within the component-ref element in the data stream if such file exists.
+This option works only with SCAP 1.3 source data streams. It can't be used with SCAP 1.2 source data streams.
 .RE
 
 .TP
@@ -682,6 +687,7 @@ Allow download of remote components referenced from data stream.
 .TP
 \fB\-\-local-files DIRECTORY\fR
 Instead of downloading remote data stream components from the network, use data stream components stored locally as files in the given directory. In place of the remote data stream component OpenSCAP will attempt to use a file whose file name is equal to @name attribute of the uri element within the catalog element within the component-ref element in the data stream if such file exists.
+This option works only with SCAP 1.3 source data streams. It can't be used with SCAP 1.2 source data streams.
 .RE
 .TP
 .B \fBsds-validate\fR SOURCE_DS