Skip to content

Clarify the '--local-files' option #2266

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
evgenyz merged 1 commit into from
Oct 14, 2025
Merged

Clarify the '--local-files' option #2266

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions docs/manual/manual.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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>>.
19 changes: 19 additions & 0 deletions src/DS/ds_sds_session.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
11 changes: 10 additions & 1 deletion tests/DS/test_ds_use_local_remote_resources.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@
# Jan Černý <jcerny@redhat.com>

set -e -o pipefail
set -x

. $builddir/tests/test_common.sh

Expand Down Expand Up @@ -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"
6 changes: 6 additions & 0 deletions utils/oscap.8
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading