diff --git a/src/specifications/profile-resolution/profile-resolution-examples/example-set.xspec b/src/specifications/profile-resolution/profile-resolution-examples/example-set.xspec index b5d8326d73..e17d79042b 100644 --- a/src/specifications/profile-resolution/profile-resolution-examples/example-set.xspec +++ b/src/specifications/profile-resolution/profile-resolution-examples/example-set.xspec @@ -3,7 +3,8 @@ xmlns:opr="http://csrc.nist.gov/ns/oscal/profile-resolution" stylesheet="../../../utils/util/resolver-pipeline/oscal-profile-RESOLVE.xsl" run-as="external"> - + + + + { + string-join(($message-type, $error-code, $text),': ') + } + + + \ No newline at end of file diff --git a/src/utils/util/resolver-pipeline/oscal-profile-RESOLVE.xsl b/src/utils/util/resolver-pipeline/oscal-profile-RESOLVE.xsl index 025a5785a9..e4ba2066ba 100644 --- a/src/utils/util/resolver-pipeline/oscal-profile-RESOLVE.xsl +++ b/src/utils/util/resolver-pipeline/oscal-profile-RESOLVE.xsl @@ -1,11 +1,10 @@ + + off - - - - - - - ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$ - - - - - - - - - - - - - - - - - - 00000000-0000-4000-B000-000000000000 - - - + - + + + + @@ -109,8 +86,10 @@ - - + + + + diff --git a/src/utils/util/resolver-pipeline/oscal-profile-resolve-metadata.xsl b/src/utils/util/resolver-pipeline/oscal-profile-resolve-metadata.xsl index 2f45c909bd..da67371d88 100644 --- a/src/utils/util/resolver-pipeline/oscal-profile-resolve-metadata.xsl +++ b/src/utils/util/resolver-pipeline/oscal-profile-resolve-metadata.xsl @@ -6,29 +6,53 @@ xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:math="http://www.w3.org/2005/xpath-functions/math" xmlns:opr="http://csrc.nist.gov/ns/oscal/profile-resolution" - exclude-result-prefixes="xs math o opr" + xmlns:u="http://csrc.nist.gov/ns/uuid" + exclude-result-prefixes="xs math o opr u" xpath-default-namespace="http://csrc.nist.gov/ns/oscal/1.0" > - + + + + + + + + + + + urn:UNKNOWN - - - - ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$ + + - - - + + + + + + - + @@ -55,13 +80,34 @@ + + + + + + + + + + + + + + - + - + diff --git a/src/utils/util/resolver-pipeline/readme.md b/src/utils/util/resolver-pipeline/readme.md index aa9cadeb67..0e8913a01b 100644 --- a/src/utils/util/resolver-pipeline/readme.md +++ b/src/utils/util/resolver-pipeline/readme.md @@ -1,33 +1,49 @@ -## Resolver pipeline +## Profile Resolver Pipeline -Profile resolution is implemented here as a set of XSLT transformations to be performed in sequence, applied to defined inputs (a **source profile** with imported **catalog** sources) to produce defined outputs (a **profile resolution result** in the form of a catalog). The word **baseline** is also used to refer to a particular profile in application, whether in its unprocessed form or its resolved, serialized form. +Profile resolution is implemented here as a sequence of XSLT transformations. The sequence applies to defined inputs (a **source profile** with imported **catalog** sources) and produces defined outputs (a **profile resolution result** in the form of a catalog). The word **baseline** also refers to a particular profile in application, whether in its unprocessed form or its resolved, serialized form. -The sequence reflects and roughly corresponds to the three steps in profile resolution described for OSCAL in the [Profile Resolution Specification](https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/): +The sequence of XSLT transformations reflects and roughly corresponds to the steps in profile resolution described for OSCAL in the [Profile Resolution Specification](https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/): -- **selection** (importing catalogs or profiles and selecting controls from them) +- **selection**: importing catalogs or profiles, and selecting controls from them -- **organization (merging)** i.e. specifying how selected controls are to be organized in representation +- **organization (merging)**: organizing the selected controls for the output representation -- **modification** - setting parameters and potentially supplementing, amending or editing control text +- **modification**: setting parameters and potentially supplementing, amending or editing control text -For demonstration, the expected interim results for test files are kept in the testing/\* folders +### Tests for this Implementation -Note that these interim results are *not always valid to any OSCAL schema* while at the same time they are quite close to OSCAL profile and catalog syntax. +The `testing/*` folders contain XSpec tests that indicate expected interim results of each XSLT transformation in the sequence. -Testing files for profile resolution in general are kept [with the specification](../../../specifications/profile-resolution). The testing files in this subdirectory are only for this implementation. +Note that these interim results are *not necessarily valid to any OSCAL schema*, although they are quite close to OSCAL profile and catalog syntax. -### Invoking the XSLT: +The files in `testing/*` are only for this implementation. Implementation-independent tests and sample files for profile resolution are [with the specification](../../../specifications/profile-resolution). -Use a recent version of Saxon for best results -- although we would also be *very interested* to hear from users of other XSLT engines conformant to the 3.1 family of XML standards (XSLT/XPath/XDM/XQuery). +### Invoking the XSLT -The main entry point for the transformation pipeline is the dynamic build XSLT called `oscal-profile-RESOLVE.xsl`, which invokes the core transformation steps in sequence, taking the source profile document as primary input. Load Saxon with your document and this stylesheet as follows (for example): +Use a recent version of Saxon for best results — although we would also be *very interested* to hear from users of other XSLT engines conformant to the 3.1 family of XML standards (XSLT/XPath/XDM/XQuery). + +The entry point for the transformation pipeline is `oscal-profile-RESOLVE.xsl`, which invokes the transformation steps in sequence, taking the source profile document as primary input. Load Saxon with your document and this stylesheet as follows (for example): ```bash > java -cp saxon-he-10.0.jar net.sf.saxon.Transform -t -s:YOUR_PROFILE_DOCUMENT.xml -xsl:path/to/oscal-profile-RESOLVE.xsl -o:YOUR_RESULT_BASELINE.xml ``` -Alternatively, set up the bindings in an IDE or programmed environment that has XSLT 3.1 support. +You can optionally set one or more of the parameters listed in the following table, using syntax `name=value` at the end of the command above. The sequence of parameters is not significant. + +For example, +```bash +> java -cp saxon-he-10.0.jar net.sf.saxon.Transform -t -s:YOUR_PROFILE_DOCUMENT.xml -xsl:path/to/oscal-profile-RESOLVE.xsl -o:YOUR_RESULT_BASELINE.xml uuid-method=random-xslt hide-source-profile-uri=true +``` +| Name | Description | Default | +|---|---|---| +| `hide-source-profile-uri` | If `true`, the output catalog's metadata does not record the source profile's URI. | `false` | +| `path-to-source` | Path from output catalog to location of source profile. | None | +| `top-uuid` | UUID value for top-level element in output catalog, if `uuid-method` is `user-provided`. | None | +| `uuid-method` | Method for computing UUID of top-level element in output catalog. Valid values are: `random-xslt`, in which case the `random-number-generator` XPath function must be available; `random-java`, in which case the `java.util.UUID.randomUUID()` Java method must be available; `user-provided`, in which case you must specify the `top-uuid` parameter; `web-service`, referring to the `uuid-service` parameter value; and `fixed`. | `fixed`| +| `uuid-service` | URI for a web service that produces a UUID, if `uuid-method` is `web-service`.| `https://www.uuidgenerator.net/api/version4`| + +Alternatively, set up the bindings in an IDE or programming environment that has XSLT 3.1 support. -Note that URIs (addresses) given in a profile document must link correctly as absolute or relative paths to their imported catalogs, as demonstrated in examples. +Note that URIs (addresses) given in a profile document must link correctly as absolute or relative paths to their imported catalogs, as demonstrated in [examples](../../../specifications/profile-resolution/profile-resolution-examples). -A captured and serialized profile resolution will take the form of an OSCAL catalog, and be valid to the catalog schema for correctly formed inputs. +A serialized output of profile resolution takes the form of an OSCAL catalog. Assuming inputs are correctly formed, the output is valid to the catalog schema. diff --git a/src/utils/util/resolver-pipeline/testing/2_metadata/metadata.xspec b/src/utils/util/resolver-pipeline/testing/2_metadata/metadata.xspec index a670f3b298..2cb9d2fade 100644 --- a/src/utils/util/resolver-pipeline/testing/2_metadata/metadata.xspec +++ b/src/utils/util/resolver-pipeline/testing/2_metadata/metadata.xspec @@ -1,162 +1,359 @@ - - - - - - - - - + + - - - + + + + Test Profile + 2021-05-30T14:39:35.84-04:00 + 1.3 + 1.0.1 + + - Small Profile for Testing - 2019-11-13T12:13:58.517-05:00 + XYZ Tiny Catalog + 2020-05-30T14:51:42.355-04:00 1.0 - 1.0-rc2 + 1.0.0 + + Internal link within catalog - - + + Group X of XYZ + + + + - - - - Small Profile for Testing - ... - 1.0 - 1.0-rc2 - - - - + + + text + + + + + + + + + - + + + + - + + + + + + + + + + + + + + + + + + - Pathological Profile - 2019-11-13T12:41:07.061-05:00 - 1.0 - 1.0-rc2 + Test Profile + ... + 1.3 + ... + + - + + + + + + - ABC Catalog - 2019-11-01T10:16:22.939-04:00 + Pathological Profile + 2019-11-13T12:41:07.061-05:00 + 2019-11-13T12:41:07.061-05:00 1.0 1.0-rc2 + ...doi... + + + Standing Committee + + - - - - - - + + + - Pathological Profile + ... + 2019-11-13T12:41:07.061-05:00 ... - 1.0 - 1.0-rc2 - - - - - - - - - - - Pathological Profile - 2019-11-13T12:41:07.061-05:00 - 1.0 - 1.0-rc2 + ... + ... + ...doi... + + Standing Committee - + + + + + - ABC Catalog - 2019-11-01T10:16:22.939-04:00 + Pathological Profile + 2019-11-13T12:41:07.061-05:00 1.0 1.0-rc2 + + - - - - - - + + + - Pathological Profile + ... ... - 1.0 - 1.0-rc2 - - - - Standing Committee - - - - - - - - - - - - Pathological Profile - 2019-11-13T12:41:07.061-05:00 - 1.0 - 1.0-rc2 - Internal link - - - Standing Committee - - + ... + ... + + + + - + + + + + - ABC Catalog - 2019-11-01T10:16:22.939-04:00 + Pathological Profile + 2019-11-13T12:41:07.061-05:00 1.0 1.0-rc2 + Internal link - - - - - - + + + - Pathological Profile + ... ... - 1.0 - 1.0-rc2 - + ... + ... + + Internal link - - - Standing Committee - - - - - + + + + + + + + + + + + + + + + ... + + + + + + + + + + + + + + + + + + + + 1.3 + + + + + ... + + + + + + + + 1.0.3 + + + + + 1.0.1 + + + + + 1.0.4 + + + + + 1.0.2 + + + + + + 1.0.4 + + + + + + + 1.0.4 + + + + 1.0.1 + + + + + + 1.0.4 + + + + + + + 1.4.0 + + + + 1.2.0 + + + + + + 1.1.0 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/utils/util/resolver-pipeline/testing/2_metadata/uuid-method-choice.xspec b/src/utils/util/resolver-pipeline/testing/2_metadata/uuid-method-choice.xspec new file mode 100644 index 0000000000..f1a5f6b8e3 --- /dev/null +++ b/src/utils/util/resolver-pipeline/testing/2_metadata/uuid-method-choice.xspec @@ -0,0 +1,86 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/utils/util/resolver-pipeline/testing/2_metadata/uuid-value.txt b/src/utils/util/resolver-pipeline/testing/2_metadata/uuid-value.txt new file mode 100644 index 0000000000..a8e02be099 --- /dev/null +++ b/src/utils/util/resolver-pipeline/testing/2_metadata/uuid-value.txt @@ -0,0 +1 @@ +309deb03-491b-4677-9148-bc1b79a21c9c \ No newline at end of file diff --git a/src/utils/util/resolver-pipeline/uuid-method-choice.xsl b/src/utils/util/resolver-pipeline/uuid-method-choice.xsl new file mode 100644 index 0000000000..97c028fb55 --- /dev/null +++ b/src/utils/util/resolver-pipeline/uuid-method-choice.xsl @@ -0,0 +1,89 @@ + + + + + + + + + + + + + + + + + + + + + ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$ + 00000000-0000-4000-B000-000000000000 + + + + + + + + Warning + top-uuid value, '{$top-uuid}', does not meet UUID requirements. Using default UUID instead. + + + + + + + + + + + + + + Warning + uuid-method, '{$uuid-method}', is not available. Using default UUID instead. + + + + + + + + + Warning + uuid-service, '{$uuid-service}', is not available. Using default UUID instead. + + + + + + + + + Warning + uuid-method, '{$uuid-method}', is not recognized. Using default UUID instead. + + + + + + + \ No newline at end of file